API

Programmatically query and obtain the data displayed on TLD-List.

We are working on improving our API

A robust and intuitive JSON API will be available shortly. This API will let enterprise users to query data from TLD-List's live database. Nearly all data that is displayed on this website will be available from the API and it will allow filtering using client supplied parameters.

Overview

The TLD-List v1 API can be used to retrieve data displayed on TLD-List from its live database.

The API accepts HTTP POSTs containing JSON data and responds with JSON data. Requirements for all API method requests:

Requests must be made using the HTTP POST method
Requests must have a JSON body containing a valid public and private API key pair for authentication
Requests must include the header: Content-Type: application/json

Parameters are passed to the API as key/values in the JSON encoded request body.

The base URL for all API requests is:

https://api.tld-list.com/v1

Authentication

Authentication is performed by passing a public API key and a private API key in the JSON body posted to the method URL. All API calls must include a valid API keypair. API keypairs can be generated in your TLD-List account under the API tab.

Visit Account > API to create API keys.

API keys are passed in the JSON request body using the parameters apiKeyPublic (your public key) and apiKeyPrivate (your private key).

Example authentication parameters

'{'
  "apiKeyPublic":"MY_PUBLIC_KEY", 
  "apiKeyPrivate":"MY_PRIVATE_KEY"
'}'

Response

All successful API responses will have a 200 SUCCESS HTTP status code and a JSON encoded body. Any other HTTP status code in the response indicates the request failed and an error has occurred.

JSON response objects returned by the API will have the following structure:

Key	Type	Description
`status`	string	Specifies the status of the request. `SUCCESS` indicates the API call was successful, `FAIL` indicates the request failed.
`errors`	array of objects	Array of objects representing the errors that occurred. Each error object will contain: `code`: string identifying the type of error `message`: human-readable string describing the error `parameter`: optional string or array of strings indicating an issue with a certain parameter(s) passed in the request. If no errors occurred, the `errors` array will be empty. See Error Codes for more information.
`seconds`	number	Amount of time the API server took to generate a response (in seconds).
`data`	string\|array\|object	An object, array, or string containing the requested data.

Example failed response object with errors

'{'
   "errors" : [
      '{' 
         "code" : "PARAMETER_INVALID",
         "message" : "pricetypes parameter must be a non-empty array",
         "parameter" : "pricetypes"
      '}',
      '{' 
         "code" : "PARAMETER_INVALID",
         "message" : "includeRegistrars parameter contains invalid registrar names: foobar",
         "parameter" : "includeRegistrars"
      '}'
   ],
   "seconds" : 0.001,
   "status" : "FAIL"
'}'

Example successful response object

'{'
   "data" : [
      '{' 
         "cheapest" : '{' 
            "renewal" : [
               '{' 
                  "id" : "sav",
                  "name" : "Sav",
                  "price" : "8.38"
               '}'
            ],
         '}',
         "currency" : "USD",
         "name" : "com",
         "registrarsIncluded" : 58,
         "registrarsTotal" : 58
      '}'
   ],
   "errors" : [],
   "seconds" : 0.001,
   "status" : "SUCCESS"
'}'

Common Response Objects

Some of the API methods return data objects that have the same structure. These common data objects are described in detail below.

RegistrarPricing

Describes a registrar's retail pricing for an extension for a particular pricetype (register, renewal, transfer), including additional details such as special terms, fees, tax, and promotions.

Path	Type	Description
`id`	string	Registrar ID string that uniquely identifies the registrar.
`name`	string	Display name of registrar.
`price`	string	The registrar's final retail price for the extension and pricetype. Note: this field is only present when the RegistrarPricing object is nested in the context of a pricetype (for example, in the response from getCheapestRegistrars).
`priceOriginal`	string	The registrar's regular retail price for the extension as a numeric string. This field will only be present if `price` is a promotional price. Note: this field is only present when the RegistrarPricing object is nested in the context of a pricetype (for example, in the response from getCheapestRegistrars).
`pricetype`	string	The type of extension pricing, one of: `register`, `renewal`, `transfer`. Note: this field is only present when the RegistrarPricing object is nested in the context of a pricetype (for example, in the response from getCheapestRegistrars).
`prices`	object	The registrar's retail pricing for the extension for all pricetypes.
`prices[pricetype]`	string	The registrar's final retail price for the extension and [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`, `restore`, `whoisprivacy`. Example: '{' "register": "8.73", "renewal": "9.73", "transfer": "9.73", "whoisPrivacy": "0.00" '}'
`pricesOriginal`	object	The registrar's regular retail pricing for the extension for all pricetypes. This field will not be present if the registrar has no active `promos`.
`pricesOriginal[pricetype]`	string	The registrar's regular retail price for the extension and [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`, `restore`, `whoisprivacy`.
`promo`	object	A RegistrarPromo object representing promotional pricing that has been applied to the registrar's price for this extension and pricetype. If no promo has been applied, this field will not be present. Example promo object: '{' "code": "MYCOUPONCODE", "amount": "20.00", "type": "discount-percent", "start": "2015-06-22T00:00:00", "end": "2025-06-22T00:00:00" '}' Note: this field is only present when the RegistrarPricing object is nested in the context of a pricetype (for example, in the response from getCheapestRegistrars).
`promos`	array of objects	Array of RegistrarPromo objects representing all active promotional pricing offered by the registrar for this extension.
`terms`	object	A collection of objects representing special terms that apply to the registrar's pricing. If no special terms apply, this field will not be present. Each sub object is keyed with a term ID: `limitPerCustomer` - specifies that the pricing is only valid for a certain number of domains per customer. `newCustomerOnly` - specifies that the pricing is only valid for new customers. `affiliateLink` - specifies that the pricing is only valid when the customer accesses the registrar's site via an affiliate link. `nameserverLockIn` - specifies that purchased domains can only use the registrar's nameservers. `idSubmissionRequired` - specifies that customer must submit their photo ID or business registration to complete a purchase. Example terms objects: '{' "limitPerCustomer": '{' "pricetype": ["register"], "count": 1 '}', "newCustomerOnly": '{' "pricetype": ["register"] '}', "affiliateLink": '{' "pricetype": ["register"] '}', "multiYearPurchaseRequired": '{' "pricetype": ["register"], "count": 2 '}', "nameserverLockIn": '{' "pricetype": ["register", "renewal", "transfer"] '}', "idSubmissionRequired": '{' "pricetype": ["register", "renewal", "transfer"] '}' '}'
`terms[term].count`	number	The quantity that the term limits the customer to. For instance, if `count = 1`, then the customer is limited to 1 domain at the specified price. This field will be not be present if it does not apply.
`terms[term].pricetype`	array of strings	The price type(s) the term applies to: `register`, `renewal`, `transfer`. This field will only be present if the pricetype of the RegistrarPricing object is not specified.
`notes`	object	A collection of objects representing notes that pertain the registrar's pricing. If there are no pricing notes, this value will be an empty object. Each sub object is keyed with a notes ID: `currencyExchangeRate`, `feeIcann`, `feeTax`, `feePayment`
`notes.feeIcann`	object	Specifies if an ICANN fee has been added to the final price for the TLD (typically $0.18 USD). If this note exists, it means the registrar does not include the ICANN fee in their advertised price, and instead adds it as an additional fee to the TLD's price at customer checkout. Example `fee_icann` note object: '{' "feeIcann": '{' "pricetype": ["register", "renewal", "transfer"], "amount": "0.18", "addedToListPrice": true '}' '}' The `pricetype` field specifies which price types are subject to the fee, and the `addedToListPrice` field indicates that the fee has been added to the final price.
`notes.feeTax`	array of objects	Specifies the various tax rates charged by a registrar, the customers that the tax applies to, and if the calculated tax has been included in the final price for the TLD. Please note that taxes are only included in the final price for the TLD if the registrar does not include the tax in their advertised prices and the tax is charged to all customers. Example `feeTax` array of objects: '{' "feeTax": [ '{' "addedToListPrice": false, "appliesToCustomers": ["eu", "us", "in"], "amountRateType": "percent", "amountRate": "13", "type": "hst" '}', '{' "addedToListPrice": false, "appliesToCustomers": ["ca"], "amountRateType": "percent", "amountRate": "5", "type": "gst" '}' ] '}'
`notes.feeTax[].type`	string	Label describing the type of tax, i.e. `'vat'` for Value Added Tax, `'gst'` for Goods and Services Tax, etc.
`notes.feeTax[].amountRate`	number\|string	Tax rate amount. This will either the tax percentage rate as a number, or the string `'~'` indicating that the tax rate varies based on customer criteria, such as location.
`notes.feeTax[].amountRateType`	string	The string value `'percent'` indicates the `amountRate` value is a numeric percentage. The string value `'percent-varies-by-location'` indicates the tax rate varies based on the customer's billing region or country.
`notes.feeTax[].appliesToCustomers`	string\|array of strings	The string `'*'` indicates the tax applies to all customers. Otherwise this value will be an array of ISO 3166-1 alpha-2 country code strings defining which countries are subject to the tax. One exception worth noting: the array may contain the non-country code string `'eu'`, which represents all countries in the European Union.
`notes.feeTax[].addedToListPrice`	boolean	Indicates if the calculated tax amount has been added to the final price.
`notes.feePayment`	object	Specifies if the registrar charges an additional fee based on the customer's payment method, and if the fee has been included in the final price for the TLD. Example `feePayment` object: '{' "feePayment": '{' "addedToListPrice": false, "amountRate": "~", "amountRateMin": "0.9", "amountRateMax": "20", "amountRateType": "percent-varies-by-method" '}' '}'
`notes.feePayment.amountRate`	string	Fee amount. This will be either the fee percentage rate as a number, or the string `'~'` indicating that the fee rate varies based on customer criteria, such as payment method.
`notes.feePayment.amountRateMin`	string	Minimum fee amount, applies only if the fee is variable.
`notes.feePayment.amountRateMax`	string	Maximum fee amount, applies only if the fee is variable.
`notes.feePayment.amountRateType`	string	The string value `'percent'` indicates the `amountRate` value is a numeric percentage. The string value `'percent-varies-by-method'` indicates the fee is a percentage that varies based on the customer's payment method.
`notes.feePayment.addedToListPrice`	boolean	Indicates if the calculated fee amount has been added to the final price.
`notes.currencyExchangeRate`	object	Specifies that the registrar's prices were listed in another national currency, and have been converted to USD. The details of the currency conversion are represented as: `base`: the registrar's pricing currency as a 3 letter code (i.e. EUR) `quote`: the currency the prices were converted to (will always be USD) `rate`: the exchange rate used to make the currency conversion. Example `currencyExchangeRate` note object: '{' "currencyExchangeRate": '{' "base": "GBP", "quote": "USD", "rate": "1.2482" '}' '}'
`threeYearValueScore`	number	A numeric measurement of value, determined by pricing and free features, for owning a domain with this extension via the registrar for a period of 3 years. The bigger the number, the more value is offered.
`currency`	string	The three-letter ISO 4217 currency code of the pricing data. This value is currently only `USD`.
`freeFeatures`	array of objects	An array of objects representing the free features the registrar offers with domain ownership. Object includes the quantity and duration of each feature. Each object is keyed with a free feature ID: `dns` - free DNS service. `whois-privacy` - WHOIS privacy service. `email-account` - free email account(s). `email-forward` - free email forwarding. `ssl-cert` - free basic SSL certificate(s). Example free feature array: [ '{' "name": "dns" '}', '{' "name": "whois-privacy" '}', '{' "name": "email-account", "count": 5 '}', '{' "name": "ssl-cert", "duration": 365 '}' ]
`freeFeatures[].count`	number	The quantity of the feature the registrar offers for free. This field will be not be present if it does not apply.
`freeFeatures[].duration`	number	The number of days the feature is offered for free by the registrar. If the `duration = 365`, then feature is offered for free for 1 year. This field will be not be present if it does not apply.

RegistrarPromo

Describes an active promotion offered by a registrar. Example:

'{' 
    "code": "MYCOUPONCODE",
    "amount": "20.00",
    "type": "discount-percent",
    "start": "2015-06-22T00:00:00",
    "end": "2025-06-22T00:00:00"
'}'

Path	Type	Description
`promo.code`	string	The promo code the customer must enter at checkout to receive the discounted promotion.
`promo.amount`	string	The numeric amount of the promotional pricing. Depending on the promo's type, this could be the discounted price (`price`), the amount subtracted from the regular price (`discount`), or the percentage amount subtracted from the regular price (`discount-percent`).
`promo.type`	string	A string representing the type of promotional pricing. Will be one of the following values: `price` - means the promo's amount field is the new discounted price `discount` - means the promo's amount field was subtracted from the regular price to obtain the applied price `discount-percent` - means the promo's amount field is a percentage, and the percentage was subtracted from the regular price to obtain the applied price.
`promo.start`	string	ISO 8601 datetime (UTC timezone) of when the promo started. Will not be present if there was no specific start date. Example: `2015-06-22T00:00:00`
`promo.end`	string	ISO 8601 datetime (UTC timezone) of when the promo will end. Will not be present if there is no specific end date. Example: `2025-06-22T00:00:00`
`promo.pricetype`	array of strings	The price type(s) the promo applies to: `register`, `renewal`, `transfer`. Note: this field is only present when nested in the context of a pricetype (for example, in the response from getCheapestRegistrars).

Error Codes

On request failure, the JSON response object can contain one or more error objects that describe what went wrong. Below are a noncomprehensive list of identifying error codes that can be set in the error object's code field.

Code	Description
502	API server is temporarily unavailable.
RATE_LIMITED	Number of client API requests exceeded allowed maximum.
INVALID_METHOD	The requested API method doesn't exist.
SYSTEM	An unknown system error occurred.
RESPONSE_TIMEOUT	API server timed out while generating a response.
PARAMETER_REQUIRED	A required parameter for the called method was not provided by the client.
ACCOUNT_INACTIVE	Client's account is no longer active and a subscription renewal is required for API access.
NO_ACCESS	Client's account level does not grant API access. An account upgrade is required for API access.
AUTH_INVALID	Authentication failed: the provided API keys are inactive or invalid.
CLIENT_IPS_EXCEEDED	The maximum unique client IPs allowed to access the API for the provided API keypair has been exceeded.
REQUEST_ENDED_BY_CLIENT	The request was terminated by the client before a response could be generated.

Limits

Usage of the API is subjected to certain limits to prevent abuse. These usage limitations are shown below and are subject to change without notice.

Type	Description
API Keys Per Account	3
Rate Limit	100 maximum requests per 15 minutes
Client IP Addresses Per API Key	5 unique client IP addresses per key per 1440 minutes

Extension Methods

get

Returns extensions and their associated pricing and details data. This method is akin to retrieving the data displayed on one or more TLD detail pages (for example, .com), with the exception of "Cheapest Price History" data, which is not returned by this method (see the getAggregateHistory method for historical data).

API endpoint: https://api.tld-list.com/v1/extension/get

Response time: ~12 seconds for all extensions, ~6 seconds < 2000 extensions, ~2 seconds < 100 extensions

Request parameters

Key	Type	Required	Description
`extensions`	array of strings	No	Specifies which extensions to retrieve. Do not include a preceding dot. Extension names can be unicode or their punycode equivalent. If omitted, all extensions listed on TLD-List will be returned. Example: `"extensions": ["com", "io", "co.uk", "移动", "xn--p1ai"]`
`includeFields`	array of strings	No	Specify certain data to return by key name. Keys not submitted in this parameter will be omitted. By default, all available fields are returned. See the response table for a list of available fields. Nested fields are not supported. Example: `"includeFields": ["name", "registrars", "dnssecSupported"]`
`excludeFields`	array of strings	No	Specify certain data to exclude by key name. Keys submitted in this parameter will be omitted. By default, no fields are excluded. See the response table for a list of available fields. Nested fields are not supported. Example: `"excludeFields": ["available", "syntax", "sponsor"]`
`includeRegistrars`	array of strings	No	The string IDs of active registrars to include in the results. Use the getIds method to obtain a list of IDs of all the registrars actively listed on TLD-List. Example: `"includeRegistrars": ["godaddy", "porkbun", "namecheap"]`
`excludeRegistrars`	array of strings	No	The string IDs of active registrars to exclude in the results. Use the getIds method to obtain a list of IDs of all the registrars actively listed on TLD-List. Example: `"excludeRegistrars": ["godaddy", "porkbun", "namecheap"]`
`omitExtensionsWithoutRegistrars`	boolean	No	When `true`, extensions that have no registrar pricing data in the results are omitted. By default, all extensions are included. Example: `"omitExtensionsWithoutRegistrars": true`

Response object

Path	Type	Description
`data`	array of objects	Array of extension names.
`data[].available`	object	Object of TLD phase availability dates.
`data[].available.general`	object	ISO 8601 datetime (UTC timezone) of when domain registration is available to the general public.
`data[].available.sunrise`	object	Object of `start` and `end` datetime ranges representing the TLD's Sunrise phase (when trademark owners can begin to apply for registration of applicable domains). Example: '{' "sunrise": '{' "start": "2017-06-19T00:00:00.000Z", "end": "2017-08-21T00:00:00.000Z" '}' '}'
`data[].available.trademark`	object	Object of `start` and `end` datetime ranges representing the TLD's Trademark phase (period when trademark holders will be notified by the Trademark Clearinghouse if a domain is registered matching their mark). Example: '{' "trademark": '{' "start": "2019-06-18T00:00:00.000Z", "end": "2020-09-21T00:00:00.000Z" '}' '}'
`data[].available.other`	array of objects	Array of objects representing various launch phases of the TLD and their datetime ranges, such as "Land Rush" and "Qualified Launch Program". Example: '{' "other": [ '{' "end": "2020-09-18T00:00:00.000Z", "name": "Limited Community Priority Period", "start": "2019-09-17T00:00:00.000Z", "type": "limited-registration-period" '}', '{' "end": "2018-07-03T00:00:00.000Z", "name": "Restricted Land Rush 1", "start": "2017-10-23T00:00:00.000Z", "type": "limited-registration-period" '}', '{' "end": "2019-09-16T00:00:00.000Z", "name": "Invitation Priority Access", "start": "2017-08-22T00:00:00.000Z", "type": "limited-registration-period" '}', '{' "end": "2017-08-21T00:00:00.000Z", "name": "Qualified Launch Program", "start": "2017-06-19T00:00:00.000Z", "type": "qualified-launch-program" '}' ] '}'
`data[].average`	object	Object containing the average price of the extension, by pricetype, for the included registrars. Example: '{' "average": '{' "register": "7.63", "renewal": "13.63", "transfer": "9.63" '}' '}'
`data[].average[pricetype]`	string	The average price of the extension as a numeric string for [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`, `restore`, `whoisprivacy`.
`data[].category`	string	The categories the TLD has been classified under. Each object in the array represents a category and contains the following fields: `id` - integer category ID used internally by TLD-List. `idstr` - alternate string category ID. `name` - category name in English. `desc` - category description in English. Example category array: [ '{' "id": 4, "idstr": "services", "name": "Services", "desc": "TLDs for representing the service industry." '}', '{' "id": 6, "idstr": "food", "name": "Food & Drink", "desc": "Domain extensions for dining, cooking, restaurants, and beverages." '}' ]
`data[].dnssecSupported`	boolean	If the registry's DNS zone supports DNS Security Extensions (DNSSEC).
`data[].hasPremiumDomains`	object	Object of [pricetype] keys and boolean values, representing if the registry charges higher prices for select "premium" domain names. Example: '{' "hasPremiumDomains": '{' "register": false, "renewal": false '}' '}'
`data[].infoUpdated`	string	ISO 8601 datetime (UTC timezone) of when the TLD's basic info (restrictions, availability dates, etc) was last checked and updated. Note: a new `updated.info` date does not necessarily indicate that any data change occurred. It only indicates when the data was last checked and set.
`data[].intendedUsage`	string	General information about how the extension is expected to be used by registrants.
`data[].language`	string	The ISO 639-1 2 character language code. If the language is English-based or unknown, this field will be not be present.
`data[].level`	integer	Integer representing the extension's domain level. 1 = top-level domain, 2 = second-level domain, 3 = third-level domain, etc.
`data[].localPresenceRequired`	boolean	If the registry requires the registrant to have a physical address local to the region.
`data[].median`	object	Object containing the median price of the extension, by pricetype, for the included registrars. Example: '{' "median": '{' "register": "3.17", "renewal": "20.17", "transfer": "8.17" '}' '}'
`data[].median[pricetype]`	string	The median price of the extension as a numeric string for [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`, `restore`, `whoisprivacy`.
`data[].name`	string	Unicode name of the domain extension.
`data[].nameservers`	array	The registry's root nameservers that store registered domains' authoritative nameservers. Example nameservers array: '{' "nameservers": [ '{' "host": "a.gtld-servers.net", "ipv4": "192.5.6.30", "ipv6": "2001:503:a83e:0:0:0:2:30" '}', '{' "host": "b.gtld-servers.net", "ipv4": "192.33.14.30", "ipv6": "2001:503:231d:0:0:0:2:30" '}' ] '}'
`data[].parentTld`	string	The extension's parent top-level domain. If this is a TLD, this field will not be present.
`data[].pricingUpdated`	string	ISO 8601 datetime (UTC timezone) of when the TLD's registrar pricing was last checked and updated. Note: a new `updated.pricing` date does not necessarily indicate that any data change occurred. It only indicates when the data was last checked and set.
`data[].punycode`	string	Punycode name of the domain extension. Only present for IDN extensions.
`data[].registerMaxYears`	integer	Maximum years that a domain can be registered at time of purchase.
`data[].registerMinYears`	integer	Minimum years that a domain can be registered at time of purchase.
`data[].registrarsIncluded`	integer	Count of registrars included in the returned `registrars` array.
`data[].registrarsTotal`	integer	Total active registrars that sell the extension.
`data[].registrars`	array of objects	Array of RegistrarPricing object(s) containing registrar pricing and features data.
`data[].registryUrl`	string	The registry's official website for TLD registration information.
`data[].renewalMinYears`	integer	Minimum allowable years that a domain can be renewed.
`data[].restrictions`	string	A short description of the TLD's registration restrictions and requirements. If there are no restrictions, this field will not be present.
`data[].sponsor`	object	Object containing data about the extension's sponsoring organization or management organization.
`data[].sponsor.name`	string	The name of the extension's ICANN approved sponsoring organization or ccTLD management organization.
`data[].sponsor.address`	string	Physical location of the sponsoring organization or ccTLD management organization. Example address array: '{' "sponsor": '{' "address": [ "Minerva House", "Edmund Halley Road", "Oxford Science Park", "Oxford OX4 4DQ", "United Kingdom" ] '}' '}'
`data[].sponsorParentCompany`	string	Name of the entity that owns controlling interest in the sponsor organization.
`data[].romanized`	string	The TLD transcribed into latin characters. If the language is English-based, or unknown, this field will not be present.
`data[].rtl`	string	If the extension is read from "right-to-left" (ie. Arabic TLDs), this value will be true. If it is read from "left-to-right", this value will be false. If unknown, this value will not be present.
`data[].syntax`	object	Object containing details about the extension's allowed domain name rules and restrictions.
`data[].syntax.minChars`	integer	Minimum number of characters in label allowed to be registered.
`data[].syntax.maxChars`	integer	Maximum number of characters in label allowed to be registered.
`data[].targetMarket`	string	The people or entities the TLD is intended to serve.
`data[].translation`	string	The English translation of the TLD. If the TLD is already English-based, or the translation is unknown, this value will not be present.
`data[].type`	string	The type of TLD identified by one of the following strings: `gTLD:` generic top-level domain. `ccTLD:` country-code top-level domain. `grTLD:` generic-restricted top-level domain. `sTLD:` sponsored top-level domain.
`data[].wholesale`	object	Object containing the wholesale prices of the extension by pricetype. Wholesale prices are the prices charged by the registry to a registrar for domain name purchases. Example: '{' "wholesale": '{' "register": "8.97", "renewal": "8.97", "transfer": "8.97" '}' '}'
`data[].whoisPrivacySupported`	boolean	If the extension allows WHOIS Privacy services to mask registrants' names and contact information. If unknown, this field will not be present.
`data[].whoisServer`	boolean	Host name of registry's server that stores domain registrant contact information.

Example request/response

curl -X POST https://api.tld-list.com/v1/extension/get -H 'Content-Type: application/json' -d ''{' "extensions": ["com"], "includeRegistrars": ["porkbun","godaddy","epik"], "apiKeyPublic":"MY_PUBLIC_KEY","apiKeyPrivate":"MY_PRIVATE_KEY"'}' 

'{' 
   "data" : [
      '{' 
         "average" : '{' 
            "register" : "7.63",
            "renewal" : "13.63",
            "transfer" : "9.63"
         '}',
         "clicks" : 226,
         "dnssecSupported" : true,
         "hasPremiumDomains" : '{' 
            "register" : false,
            "renewal" : false
         '}',
         "infoUpdated" : "2023-02-04T11:05:09",
         "level" : 1,
         "localPresenceRequired" : false,
         "median" : '{' 
            "register" : "3.17",
            "renewal" : "20.17",
            "transfer" : "8.17"
         '}',
         "name" : "com",
         "nameservers" : [
            '{' "host" : "a.gtld-servers.net", "ipv4" : "192.5.6.30", "ipv6" : "2001:503:a83e:0:0:0:2:30" '}',
            '{' "host" : "b.gtld-servers.net", "ipv4" : "192.33.14.30", "ipv6" : "2001:503:231d:0:0:0:2:30" '}',
            '{' "host" : "c.gtld-servers.net", "ipv4" : "192.26.92.30", "ipv6" : "2001:503:83eb:0:0:0:0:30" '}',
            '{' "host" : "d.gtld-servers.net", "ipv4" : "192.31.80.30", "ipv6" : "2001:500:856e:0:0:0:0:30" '}',
            '{' "host" : "e.gtld-servers.net", "ipv4" : "192.12.94.30", "ipv6" : "2001:502:1ca1:0:0:0:0:30" '}',
            '{' "host" : "f.gtld-servers.net", "ipv4" : "192.35.51.30", "ipv6" : "2001:503:d414:0:0:0:0:30" '}',
            '{' "host" : "g.gtld-servers.net", "ipv4" : "192.42.93.30", "ipv6" : "2001:503:eea3:0:0:0:0:30" '}',
            '{' "host" : "h.gtld-servers.net", "ipv4" : "192.54.112.30", "ipv6" : "2001:502:8cc:0:0:0:0:30" '}',
            '{' "host" : "i.gtld-servers.net", "ipv4" : "192.43.172.30", "ipv6" : "2001:503:39c1:0:0:0:0:30" '}',
            '{' "host" : "j.gtld-servers.net", "ipv4" : "192.48.79.30", "ipv6" : "2001:502:7094:0:0:0:0:30" '}',
            '{' "host" : "k.gtld-servers.net", "ipv4" : "192.52.178.30", "ipv6" : "2001:503:d2d:0:0:0:0:30" '}',
            '{' "host" : "l.gtld-servers.net", "ipv4" : "192.41.162.30", "ipv6" : "2001:500:d937:0:0:0:0:30" '}',
            '{' "host" : "m.gtld-servers.net", "ipv4" : "192.55.83.30", "ipv6" : "2001:501:b1f9:0:0:0:0:30" '}'
         ],
         "pricingUpdated" : "2023-02-04T11:04:33",
         "registerMaxYears" : 10,
         "registerMinYears" : 1,
         "registrars" : [
            '{' 
               "currency" : "USD",
               "freeFeatures" : [ '{' "name" : "dns" '}', '{' "name" : "whois-privacy" '}' ],
               "id" : "godaddy",
               "name" : "GoDaddy",
               "notes" : '{' 
                  "feeIcann" : '{' "addedToListPrice" : true, "amount" : "0.18", "pricetype" : ["register","renewal","transfer"] '}',
                  "feeTax" : [
                     '{' "addedToListPrice" : false, "amountRate" : "~", "amountRateType" : "percent-varies-by-location", "appliesToCustomers" : ["eu"], "type" : "vat" '}',
                     '{' "addedToListPrice" : false, "amountRate" : "15", "amountRateType" : "percent", "appliesToCustomers" : ["in"], "type" : "gst" '}',
                     '{' "addedToListPrice" : false, "amountRate" : "10", "amountRateType" : "percent", "appliesToCustomers" : ["au"], "type" : "gst" '}'
                  ]
               '}',
               "prices" : '{' "register" : "3.17", "renewal" : "20.17", "transfer" : "8.17", "whoisPrivacy" : "0.00" '}',
               "pricesOriginal" : '{' "register" : "10.18" '}',
               "promos" : [ '{' "amount" : "2.99", "code" : "GDD2dom", "pricetype" : ["register"], "start" : "2023-01-01T00:00:00", "type" : "price" '}' ],
               "terms" : '{' "limitPerCustomer" : '{' "count" : 1, "pricetype" : ["register"] '}' '}',
               "threeYearValueScore" : "5.76"
            '}',
            '{' 
               "currency" : "USD",
               "freeFeatures" : [ '{' "name" : "whois-privacy" '}', '{' "name" : "dns" '}' ],
               "id" : "epik",
               "name" : "Epik",
               "prices" : '{' "register" : "9.99", "renewal" : "10.99", "restore" : "90.00", "transfer" : "9.99", "whoisPrivacy" : "0.00" '}',
               "threeYearValueScore" : "8.29"
            '}',
            '{' 
               "currency" : "USD",
               "freeFeatures" : [ '{' "name" : "whois-privacy" '}', '{' "name" : "dns" '}', '{' "name" : "email-forward" '}', '{' "name" : "ssl-cert" '}' ],
               "id" : "porkbun",
               "name" : "Porkbun",
               "prices" : '{' "register" : "8.73", "renewal" : "9.73", "transfer" : "9.73", "whoisPrivacy" : "0.00" '}',
               "pricesOriginal" : '{' "register" : "9.73" '}',
               "promos" : [ '{' "amount" : "1.00", "code" : "AWESOMENESS", "pricetype" : ["register"], "type" : "discount" '}' ],
               "terms" : '{' "limitPerCustomer" : '{' "count" : 1, "pricetype" : ["register"] '}' '}',
               "threeYearValueScore" : "16.03"
            '}'
         ],
         "registryUrl" : "http://www.verisigninc.com",
         "renewalMinYears" : 1,
         "rtl" : false,
         "sponsor" : '{' 
            "address" : ["12061 Bluemont Way", "Reston Virginia 20190", "United States"],
            "name" : "VeriSign Global Registry Services"
         '}',
         "syntax" : '{' "maxChars" : 63, "minChars" : 2 '}',
         "type" : "gTLD",
         "whoisPrivacySupported" : true,
         "whoisServer" : "whois.verisign-grs.com",
         "wholesale" : '{' "register" : "8.97", "renewal" : "8.97", "transfer" : "8.97" '}'
      '}'
   ],
   "errors" : [],
   "seconds" : 0.068,
   "status" : "SUCCESS"
'}'

getNames

Returns all extension names.

API endpoint: https://api.tld-list.com/v1/extension/getNames

Response time: ~1 second

Request parameters

Key	Type	Required	Description
`omitExtensionsWithoutRegistrars`	boolean	No	When `true`, extensions that have no registrar pricing data in the results are omitted. Default is `false`.
`wantPunycode`	boolean	No	Encode all returned IDN extensions as punycode instead of unicode. Default is `false`.

Response object

Path	Type	Description
`data`	array of strings	Array of extension names.

Example request/response

curl -X POST https://api.tld-list.com/v1/extension/getNames -H 'Content-Type: application/json' -d ''{' "apiKeyPublic":"MY_PUBLIC_KEY","apiKeyPrivate":"MY_PRIVATE_KEY", "wantPunycode": true, "omitExtensionsWithoutRegistrars": true '}' 

'{' 
   "data" : [
      "2000.hu",
      "5g.in",
      "6g.in",
      "aaa.pro",
      "abc.br",
      "abkhazia.su",
      "abo.pa",
      "abogado",
      "abr.it",
      "abruzzo.it",
      "abudhabi",
      ...
      "xn--3bst00m",
      "xn--jvr189m",
      "xn--imr513n",
      "xn--j6w193g",
      "xn--t60b56a",
      "xn--mk1bu44c",
      "xn--3e0b707e"
   ],
   "errors" : [],
   "seconds" : 0.697,
   "status" : "SUCCESS"
'}'

getCheapestRegistrar

Returns the cheapest registrars/providers, their pricing, median price, and average price per domain extension. Extensions that are not sold by any registrars are not returned.

API endpoint: https://api.tld-list.com/v1/extension/getCheapestRegistrar

Response time: ~8 seconds for all extensions, ~4 seconds < 2000 extensions, ~1 second < 100 extensions

Request parameters

Key	Type	Required	Description
`pricetypes`	array of strings	No	Specifies the types of pricing to retrieve. If omitted, 3 pricetypes (`register`, `renewal`, `transfer`) are returned. Example: `"pricetypes": ["register", "transfer"]`
`extensions`	array of strings	No	Specifies which extensions to retrieve. Do not include a preceding dot. Extension names can be unicode or their punycode equivalent. If omitted, all extensions listed on TLD-List will be returned. Example: `"extensions": ["com", "io", "co.uk", "移动", "xn--p1ai"]`
`includeRegistrars`	array of strings	No	The string IDs of active registrars to include when determining the cheapest pricing and aggregate calculations. Registrars not specified in this parameter will be ignored. Use the getIds method to obtain a list of IDs of all the registrars actively listed on TLD-List. If this parameter is omitted, all registrars actively listed on TLD-List will be considered. Example: `"includeRegistrars": ["godaddy", "porkbun", "namecheap"]`
`excludeRegistrars`	array of strings	No	The string IDs of active registrars to exclude when determining the cheapest pricing and aggregate calculations. Use the getIds method to obtain a list of IDs of all the registrars actively listed on TLD-List. If this parameter is omitted, no registrars will be ignored. Example: `"excludeRegistrars": ["godaddy", "porkbun", "namecheap"]`
`omitExtensionsWithoutRegistrars`	boolean	No	When `true`, extensions that have no registrar pricing data in the results are omitted. This situation occurs when the passed `excludeRegistrars` and/or `includeRegistrars` parameters have caused an extension that normally has registrar pricing data to have no matching registrar pricing data. These extensions are included by default, but with empty arrays for their pricing data. Set to `true` to omit these extensions from the results. Example: `"omitExtensionsWithoutRegistrars": true`

Response object

Path	Type	Description
`data`	array of objects	Array of objects, each representing a domain extension.
`data[].name`	string	Unicode name of the domain extension.
`data[].punycode`	string	Punycode name of the domain extension. Only present for IDN extensions.
`data[].currency`	string	The three-letter ISO 4217 currency code of the pricing data. This value is currently only `USD`.
`data[].registrarsIncluded`	number	Count of registrars included in the returned pricing data.
`data[].average`	object	Object containing the average price of the extension, by pricetype, for the included registrars.
`data[].average[pricetype]`	string	The average price of the extension as a numeric string for [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`.
`data[].median`	object	Object containing the median price of the extension, by pricetype, for the included registrars.
`data[].median[pricetype]`	string	The median price of the extension as a numeric string for [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`.
`data[].cheapest`	object	Object containing the cheapest registrars for the extension by pricetype.
`data[].cheapest[pricetype]`	array of objects	Array of RegistrarPricing object(s) containing the cheapest registrar(s) by [pricetype], where the [pricetype] key is `register`, `renewal`, `transfer`. This data is an array because the cheapest price for the extension could be the same across multiple registrars.

Example request/response

curl -X POST https://api.tld-list.com/v1/extension/getCheapestRegistrar -H 'Content-Type: application/json' -d ''{' "apiKeyPublic":"MY_PUBLIC_KEY","apiKeyPrivate":"MY_PRIVATE_KEY", "includeRegistrars": ["godaddy", "namecheap", "porkbun", "namesilo", "netim"], "extensions": ["com", "co.uk"] '}' 

'{' 
   "data" : [
      '{' 
         "average" : '{' "register" : "7.85", "renewal" : "10.25", "transfer" : "11.99" '}',
         "cheapest" : '{' 
            "register" : [ '{' "currency" : "USD", "freeFeatures" : [ '{' "name" : "dns" '}', '{' "name" : "email-forward" '}', '{' "name" : "ssl-cert" '}' ], "id" : "porkbun", "name" : "Porkbun", "price" : "4.96", "priceOriginal" : "5.96", "prices" : '{' "register" : "4.96", "renewal" : "5.96" '}', "pricesOriginal" : '{' "register" : "5.96" '}', "pricetype" : "register", "promo" : '{' "amount" : "1.00", "code" : "AWESOMENESS", "type" : "discount" '}', "promos" : [ '{' "amount" : "1.00", "code" : "AWESOMENESS", "type" : "discount" '}' ], "terms" : '{' "limitPerCustomer" : '{' "count" : 1 '}' '}', "threeYearValueScore" : "18.36" '}' ],
            "renewal" : [ '{' "currency" : "USD", "freeFeatures" : [ '{' "name" : "dns" '}', '{' "name" : "email-forward" '}', '{' "name" : "ssl-cert" '}' ], "id" : "porkbun", "name" : "Porkbun", "price" : "5.96", "prices" : '{' "register" : "4.96", "renewal" : "5.96" '}', "pricetype" : "renewal", "threeYearValueScore" : "18.36" '}' ],
            "transfer" : [ '{' "currency" : "USD", "freeFeatures" : [ '{' "name" : "dns" '}' ], "id" : "godaddy", "name" : "GoDaddy", "notes" : '{' "feeTax" : [ '{' "addedToListPrice" : false, "amountRate" : "~", "amountRateType" : "percent-varies-by-location", "appliesToCustomers" : ["eu"], "type" : "vat" '}', '{' "addedToListPrice" : false, "amountRate" : "15", "amountRateType" : "percent", "appliesToCustomers" : ["in"], "type" : "gst" '}', '{' "addedToListPrice" : false, "amountRate" : "10", "amountRateType" : "percent", "appliesToCustomers" : ["au"], "type" : "gst" '}' ] '}', "price" : "11.99", "prices" : '{' "register" : "6.49", "renewal" : "11.99", "transfer" : "11.99" '}', "pricetype" : "transfer", "threeYearValueScore" : "3.46" '}' ]
         '}',
         "currency" : "USD",
         "median" : '{' "register" : "6.48", "renewal" : "10.78", "transfer" : "11.99" '}',
         "name" : "co.uk",
         "registrarsIncluded" : 4,
         "registrarsTotal" : 47
      '}',
      '{' 
         "average" : '{' "register" : "8.90", "renewal" : "14.10", "transfer" : "9.30" '}',
         "cheapest" : '{' 
            "register" : [ '{' "currency" : "USD", "freeFeatures" : [ '{' "name" : "dns" '}', '{' "name" : "whois-privacy" '}' ], "id" : "godaddy", "name" : "GoDaddy", "notes" : '{' "feeIcann" : '{' "addedToListPrice" : true, "amount" : "0.18" '}', "feeTax" : [ '{' "addedToListPrice" : false, "amountRate" : "~", "amountRateType" : "percent-varies-by-location", "appliesToCustomers" : ["eu"], "type" : "vat" '}', '{' "addedToListPrice" : false, "amountRate" : "15", "amountRateType" : "percent", "appliesToCustomers" : ["in"], "type" : "gst" '}', '{' "addedToListPrice" : false, "amountRate" : "10", "amountRateType" : "percent", "appliesToCustomers" : ["au"], "type" : "gst" '}' ] '}', "price" : "3.17", "priceOriginal" : "10.18", "prices" : '{' "register" : "3.17", "renewal" : "20.17", "transfer" : "8.17", "whoisPrivacy" : "0.00" '}', "pricesOriginal" : '{' "register" : "10.18" '}', "pricetype" : "register", "promo" : '{' "amount" : "2.99", "code" : "GDD2dom", "start" : "2023-01-01T00:00:00", "type" : "price" '}', "promos" : [ '{' "amount" : "2.99", "code" : "GDD2dom", "start" : "2023-01-01T00:00:00", "type" : "price" '}' ], "terms" : '{' "limitPerCustomer" : '{' "count" : 1 '}' '}', "threeYearValueScore" : "5.76" '}' ],
            "renewal" : [ '{' "currency" : "USD", "freeFeatures" : [ '{' "name" : "whois-privacy" '}', '{' "name" : "dns" '}', '{' "name" : "email-forward" '}', '{' "name" : "ssl-cert" '}' ], "id" : "porkbun", "name" : "Porkbun", "price" : "9.73", "prices" : '{' "register" : "8.73", "renewal" : "9.73", "transfer" : "9.73", "whoisPrivacy" : "0.00" '}', "pricetype" : "renewal", "threeYearValueScore" : "16.03" '}' ],
            "transfer" : [ '{' "currency" : "USD", "freeFeatures" : [ '{' "name" : "dns" '}', '{' "name" : "whois-privacy" '}', '{' "name" : "email-forward" '}' ], "id" : "namecheap", "name" : "Namecheap", "notes" : '{' "feeIcann" : '{' "addedToListPrice" : true, "amount" : "0.18" '}' '}', "price" : "7.16", "prices" : '{' "register" : "6.16", "renewal" : "14.16", "restore" : "13.98", "transfer" : "7.16", "whoisPrivacy" : "0.00" '}', "pricetype" : "transfer", "terms" : '{' "limitPerCustomer" : '{' "count" : 1 '}' '}', "threeYearValueScore" : "10.15" '}' ]
         '}',
         "currency" : "USD",
         "median" : '{' "register" : "10.95", "renewal" : "10.95", "transfer" : "9.95" '}',
         "name" : "com",
         "registrarsIncluded" : 5,
         "registrarsTotal" : 59
      '}'
   ],
   "errors" : [],
   "seconds" : 0.126,
   "status" : "SUCCESS"
'}'

Registrar Methods

getIds

Returns all registrar IDs, each of which uniquely identifies a registrar actively listed on TLD-List.

API endpoint: https://api.tld-list.com/v1/registrar/getIds

Response time: < 1 second

Request parameters

None

Response object

Path	Type	Description
`data`	array of strings	Array of string registrar IDs.

Example request/response

curl -X POST https://api.tld-list.com/v1/registrar/getIds -H 'Content-Type: application/json' -d ''{' "apiKeyPublic":"MY_PUBLIC_KEY","apiKeyPrivate":"MY_PRIVATE_KEY" '}' 

'{' 
   "data" : [
      "101domain",
      "123reg",
      "above.com",
      ...
      "upflare",
      "webnames.ca"
   ],
   "errors" : [],
   "seconds" : 0.001,
   "status" : "SUCCESS"
'}'

API

We are working on improving our API

Overview

Authentication

Response

Common Response Objects

RegistrarPricing

RegistrarPromo

Error Codes

Limits

Extension Methods

get

Request parameters

Response object

Example request/response

getNames

Request parameters

Response object

Example request/response

getCheapestRegistrar

Request parameters

Response object

Example request/response

Registrar Methods

getIds

Request parameters

Response object

Example request/response

Join the waitlist