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

200: application/json

{"ranks":
  [
    {
      "date": Date(YYYY-mm-dd),
      "rank": Integer
    }
  ]
}

403: Service temporarily unavailable
429: Rate limit exceeded (1 query/second)

/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} GET date: date for which to query daily list 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/create

Requires authentication

PUT

As JSON body: Configuration

200: application/json

{
  "list_id": String,
  "available": Boolean
}

400: Invalid configuration
401: Not authenticated/authorized
403: Service temporarily unavailable
429: Rate limit exceeded (1 list generated concurrently)
503: Service temporarily unavailable

Data types

Configuration
{
  "providers": [
    String("alexa"|"majestic"|"umbrella")
  ],
  "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
}

Authentication

Currently, the API supports Basic Authentication. Set your email address as username, and your API token as password.

You can test authentication using the /auth/test endpoint.