API Documentation - NameBio.com

Welcome

Thank you for your interest in the NameBio.com API. Access is provided to Business members who receive 50,000 credits per month.

Below please find detailed information on our various endpoints. If you have any questions or suggestions for new endpoints please contact us.

Rules

No multi-threading requests. You must wait for a response before sending the next request.

Do not send more than 30 requests per minute. If you receive a rate limit error you must sleep for one minute, do not just keep sending requests until you receive a successful response.

Pay attention to the number of API credits you have remaining. Do not continue sending requests after your credits are exhausted, wait until they are reset.

Keep your API key private and secure. Sharing or re-selling API access is strictly forbidden.

A citation with link is required if you display any information from our API on your website.

Failure to follow these rules will result in your API access being revoked.

Endpoints

For all endpoints you must send a POST request with the following for authentication:

Argument	Required	Notes
email (string)	Y	The email on your NameBio account.
key (string)	Y	Your private API key.

All responses will be in JSON format, and will contain at minimum:

Example Response

{
	"status": "success",
    "status_message": "",
    "credits_remaining": 1234,
}

Tip: Cache Responses

We strongly recommend that you cache responses on your server for at least 24 hours, as our database only updates once per day starting at midnight Eastern. Repeated calls within 24 hours are unlikely to contain any new information.

Endpoints » Comps

This endpoint exposes our Comps Engine, which can be seen on our Domain Details pages (when you click on a domain in the search results). You pass in a domain name and we'll return up to 25 of the most relevant sales. This is ideal for marketplaces and "For Sale" landers.

URL: https://api.namebio.com/comps/

COST: 25 Credits

Request Parameters

Argument	Required	Notes
domain (string)	Y	This is the domain you want comps for.
price_from (int)	N	Default: 0. Use this to not receive any comps below $5,000 for example.
price_to (int)	N	Default: INT_MAX. Use this to not receive any comps above $100,000 for example.
order_by (string)	N	Default: "date". Sort by "price" or "date".
order_dir (string)	N	Default: "desc". Whether to sort "asc" or "desc".
months_old (int)	N	Default: INT_MAX. How old the sales can be. Passing 12 would limit results to sales from the past year. See the discussion section below for more info.
match_sld_any_tld (string)	N	Default: "true". Values can be "true" or "false". See the discussion section below for more info.

Discussion

The months_old argument is best used when sorting by price descending, as that is likely to return results that are 10 or 15 years old. Basically you can turn it into "Give me the highest comps from the past five years." Otherwise using this argument is not recommended, as it increases the odds of receiving no results. It is generally better to show older sales than none at all.

The match_sld_any_tld argument means that if you pass us something like channels.to we'll return sales with "channels" in any TLD, for example channels.mobi. When you use this option it will include those matches regardless of your other parameters. So if you say price_from=1000 the channels.mobi sale for $551 will still show even though it is below 1000, and it will be put at the top of the results regardless of your sort method. The rest of the results will still follow your instructions on order field and direction though.

Example Request

curl -d "[email protected]&key=YOURKEY&domain=example.com&order_by=price&order_dir=desc&monthsold=60&match_sld_any_tld=false" -X POST https://api.namebio.com/comps/

Example Response

{
	"status": "success",
    "status_message": "",
    "credits_remaining": 1234,
    "domain": "example.com",
    "sld": "example",
    "tld": ".com",
    "keywords": "example",
    "comps": [
    	[
        	"similar.com",
            "500000",
            "2019-01-01",
            "Private"
        ],
        [
        	"domain.com",
            "450000",
            "2018-01-01",
            "Private"
        ]
    ],
    "attributes": [
    	"English Word",
        "High Search Volume",
        "No Advertisers",
        "Extension .com",
        "Exclude Hyphens",
        "Exclude Numbers"
    ]
}

Endpoints » CheckDomain

This endpoint allows you to check a domain to see if we have any sale records in our database, either above or below $100. If there are multiple sales we will return all of them. This is ideal for in-house tools that analyze portfolios or expired domain lists.

URL: https://api.namebio.com/checkdomain/

COST: 1 Credit

Request Parameters

Argument	Required	Notes
domain (string)	Y	This is the domain you want to check.

Example Request

curl -d "[email protected]&key=YOURKEY&domain=example.com" -X POST https://api.namebio.com/checkdomain/

Example Response

{
	"status": "success",
    "status_message": "",
    "credits_remaining": 1234,
    "domain": "example.com",
    "sales": [
    	[
            "500000",
            "2019-01-01",
            "Private"
        ],
        [
            "25000",
            "2018-01-01",
            "Auction"
        ]
    ]
}

Endpoints » DailySales

This endpoint returns all of the sales for the specified date. You can choose whether or not to include sales below $100, which affects the credits used. This is ideal for general research.

URL: https://api.namebio.com/dailysales/

COST: 250 Credits (Sales $100+), 500 Credits (All Sales)

Request Parameters

Argument	Required	Notes
date (string)	Y	YYYY-MM-DD format. Must be within the past two years. Should never be today's date, most recent is always yesterday.
include_sub_hundred (string)	N	Default: "false". Values can be "true" or "false".

Tip: Wait a Few Hours

While the daily update starts at midnight Eastern, there is a period of a few hours after that where data is in flux. That includes currency conversion, keyword parsing, categorization, manually removing questionable sales, and more. You should wait until at least 3AM Eastern to grab the latest daily sales.

Example Request

curl -d "[email protected]&key=YOURKEY&date=2019-01-01&include_sub_hundred=true" -X POST https://api.namebio.com/dailysales/

Example Response

{
	"status": "success",
    "status_message": "",
    "credits_remaining": 1234,
    "sales": [
    	[
        	"example.com"
            "500000",
            "2019-01-01",
            "Private"
        ],
        [
        	"aterribledomain.com"
            "85",
            "2019-01-01",
            "Auction"
        ]
    ]
}

Endpoints » TopSales

This endpoint returns the top X sales since a specified date. For example you can pass the date of one week ago to get the Top 10 Sales of the Week, or further limit it to "newgltds" to get the Top 10 New gTLD Sales of the Week. This is ideal for a blog sidebar or a "For Sale" lander.

URL: https://api.namebio.com/topsales/

COST: 1 Credit / Sale Record

Request Parameters

Argument	Required	Notes
date (string)	N	Default: ALL_TIME. YYYY-MM-DD format.
num_sales (int)	N	Default: 10. Max is 1000.
extension (string)	N	Default: "any". Values can be "any", "newgltds", "cctlds" or any specific extension like ".com". Separate multiple extensions with pipes, for example ".com\|.net\|.org".

Example Request

curl -d "[email protected]&key=YOURKEY&date=2019-01-01&num_sales=100&extension=.com" -X POST https://api.namebio.com/topsales/

Example Response

{
	"status": "success",
    "status_message": "",
    "credits_remaining": 1234,
    "sales": [
    	[
        	"example.com"
            "500000",
            "2019-05-31",
            "Private"
        ],
        [
        	"domain.com"
            "450000",
            "2019-04-30",
            "Auction"
        ]
    ]
}

Endpoints » KeywordStats

This endpoint returns sales stats for a given keyword including Total Sales, Dollar Volume, Average Price, Median Price, Low Price, and High Price. Optionally it can also include monthly trend data for average price and sales volume going back to 2007. The stats can include all extensions, a specified one, or one of our pre-sets (All New gTLDs or All ccTLDs). You can also restrict the underlying sales to be more recent than a certain date. This is ideal for doing keyword research.

URL: https://api.namebio.com/keywordstats/

COST: 10 Credits / Placement (without trend data), 20 Credits / Placement (with trend data)

Request Parameters

Argument	Required	Notes
keyword (string)	Y	This is the keyword you want to check.
placement (string)	N	Default: "anywhere". Values can be "anywhere", "start", "middle", "end", "exact", "prefix", or "suffix". Separate multiple placements with pipes, for example "start\|prefix".
extension (string)	N	Default: "any". Values can be "any", "newgltds", "cctlds" or any specific extension like ".com". Separate multiple extensions with pipes, for example ".com\|.net\|.org".
date (string)	N	Default: ALL_TIME. YYYY-MM-DD format. Sales used to calculate the stats will be restricted to this date or more recent.
trends (string)	N	Default: "false". Values can be "true" or "false". Whether or not to include trend data for monthly average price and monthly sales volume.

Example Request

curl -d "[email protected]&key=YOURKEY&keyword=test&placement=start|prefix|exact&extension=.com&trends=true" -X POST https://api.namebio.com/keywordstats/

Example Response

{
   "status": "success",
   "status_message": "",
   "credits_remaining": 1234,
   "stats": {
      "start": {
         "total_sales": "212",
         "dollar_volume": "542833",
         "average_price": "2561",
         "median_price": "580",
         "low_price": "100",
         "high_price": "176505",
         "trends_avg": [
            {
               "202012": 3957
            },
            {
               "202011": 336.67
            },
            {
               "202010": 103
            },
            [...]
         ],
         "trends_vol": [
            {
               "202012": 1
            },
            {
               "202011": 3
            },
            {
               "202010": 2
            },
            [...]
         ]
      },
      "prefix":{
         "total_sales": "97",
         "dollar_volume": "158459",
         "average_price": "1634",
         "median_price": "620",
         "low_price": "109",
         "high_price": "14750",
         "trends_avg": [
            {
               "202012": 3957
            },
            {
               "202011": 320
            },
            {
               "202009": 410.5
            },
            [...]
         ],
         "trends_vol": [
            {
               "202012": 1
            },
            {
               "202011": 1
            },
            {
               "202009": 2
            },
            [...]
         ]
      },
      "exact":{
         "total_sales": "0",
         "dollar_volume": null,
         "average_price": null,
         "median_price": null,
         "low_price": null,
         "high_price": null,
         "trends_avg": [
            
         ],
         "trends_vol": [
            
         ]
      }
   }
}

Errors

If an error is encountered, the "status" field in the response will be "error" instead of the usual "success". The "status_message" field will contain any relevant information related to the error, such as you being rate limited, out of credits, missing a required field, etc.

Example Response

{
	"status": "error",
    "status_message": "Insufficient API credits remaining.",
    "credits_remaining": 0,
}

Changelog

2020-12-20

Added trend data to KeywordStats endpoint.

2020-07-13

Added "date" field to KeywordStats endpoint.

2020-07-09

Improved comps matching for patterns and domain hacks.

2019-10-31

Added "In the Middle" placement for KeywordStats endpoint.

2019-08-27

Increased rate limit to 30 calls per minute from 15.

2019-08-09

Launched the first version of the API.