API documentation Alpha
Our API is available under https://tranco-list.eu/api/, and currently supports the following endpoints:
| Endpoint | Method | Parameters | Responses |
|---|---|---|---|
| /ranks/domain/{domain} | GET | domain: domain for which to query ranks in the daily lists of (at least) the past 30 days | 200: application/json {"ranks": [ { "date": Date(YYYY-mm-dd), "rank": Integer } ] } 403: Service temporarily unavailable |
| /lists/id/{list_id} | GET | list_id: ID of the list for which to query metadata | 200: application/json { "list_id": String, "available": Boolean, "download": String, "created_on": Date(YYYY-mm-ddTHH:MM:SS.ffffff), "configuration": Configuration, "failed": Boolean, "jobs_ahead": Integer } 404: No list found for given ID |
| /lists/date/{date}[?subdomains={subdomains}] | GET | date: date in YYYYmmdd format for which to query daily list metadata, or latest for the latest list subdomains: optional boolean (true/false) query parameter to use the daily list with subdomains (default if not provided: false) | 200: application/json { "list_id": String, "available": Boolean, "download": String, "created_on": Date(YYYY-mm-ddTHH:MM:SS.ffffff), "configuration": Configuration, "failed": Boolean, "jobs_ahead": Integer } 404: No list found for given ID |
| /lists/create Requires authentication | PUT | As JSON body: Configuration | 200: application/json { "list_id": String, "available": Boolean } 400: Invalid configuration |
Data types
- Configuration
{ "providers": [ String("crux"|"majestic"|"radar"|"umbrella"|"alexa"|"quantcast") ], "startDate": Date(YYYY-mm-dd), "endDate": Date(YYYY-mm-dd), "combinationMethod": String("dowdall"|"borda"), "listPrefix": Integer|"full", # Only aggregate domains from the list prefixes of length "filterPLD": "on"|"off", # Whether to retain only pay-level domains ## Parameters below are optional "inclusionDays": "on"|"off", # Only include domains if they were present for at least a given number of days "inclusionDaysValue": Integer, # Number of days for inclusionDays "inclusionLists": "on"|"off", # Only include domains if they were present in at least a given number of lists "inclusionListsValue": Integer, # Number of lists for inclusionLists "filterTLD": "include", # Whether to include only certain top-level domains "filterTLDValue": List[String], # TLDs to retain if filterTLD is "include" "filterOrganization": "on"|"off", # Whether to retain only one domain for an organization "filterSubdomain": "on"|"off", # Whether to retain only specific subdomains "filterSubdomainValue": List[String], # Subdomains to retain if filterSubdomain is "on" "filterSafeBrowsing": "on"|"off", # Whether to filter out Google Safe Browsing domains "filterCRUX": "on"|"off", # Whether to filter on Chrome User Experience Report domains "filterCRUXMonth": Date(YYYYmm)|"latest", # Month of CrUX data, or latest available month "filterCRUXType": String("global"|"country"|"region"|"subregion"), # Type of selected CrUX dataset "filterCRUXValue": List[String], # Value for selected CrUX dataset (except "global"), e.g., a list of country codes }
Authentication
Currently, the API supports Basic Authentication. (Example for Python Requests)
Set your email address as username, and your API token as password.
You can test authentication using the /auth/test endpoint.