Domainsbot MeridianBeta

Sign in

Name Suggestion

Send a word, a phrase or a name and get back domain names that suit it, check whether the names you have in mind are available, and list the top-level domains the service can suggest.

Download the description

Before you start

Each request has its own section below: what it sends, what it answers and its errors. Every answer is JSON.

Authentication
Send authtoken with each request except the list of top-level domains, which needs no token. The spelling authToken is also accepted.
A first request

Start with GET /v5/recommend. It takes a word and answers with names. Every example below already carries authtoken in its address, so each is ready to send once your token takes the place of YOUR_TOKEN.

GET /v5/availability

Check the names you send.

Request

GET /v5/availability?q=locksmith.com&func=3&authtoken=YOUR_TOKEN

Parameters

NameWhereTypeRequiredDefaultDescription
q query string yes - The name to check. Required. Repeat the parameter to check more than one name.
authtoken query string yes - The access token for this account. The spelling authToken is also accepted. Send it once.
max_results query integer no 50 How many names to return. When omitted, the service uses 50, except when status is only reg, when it uses 10. A value above 200 is read as 200. A value that is not a positive whole number is rejected.
func query string no 3 Optional. When omitted, it is read as 3, and 3 is the only value accepted. Any other value is rejected.
adult query string no - When this is yes, adult top-level domains may be included. 1, true or True means yes. Omitting it, or any other value, means no.
no_idn query string no - When this is yes, internationalized names are left out. 1, true or True means yes. Omitting it, or any other value, means no.
premium_ok query string no - When this is yes, premium names are included as well as the statuses asked for. 1, true or True means yes. Omitting it, or any other value, means no.
any_status query string no - When this is yes, every availability status is included. 1, true or True means yes. Omitting it, or any other value, means no.
status query string no ok Which availability to return. Accepted values are ok, reg, pre and res. When omitted, ok. Repeat the parameter to ask for more than one. An unrecognised value is rejected. On POST /v5/fad, pass status as a list of these values.
custom_tlds query string no - Comma-separated top-level domains to use. A value in which every entry is unusable is rejected.
tld_ok query string no - Comma-separated top-level domains to allow in addition to the account's set. Entries the service cannot use are dropped.
tld_no query string no - Comma-separated top-level domains to leave out. Entries the service cannot use are dropped.
tld_only query string no - Comma-separated top-level domains to use and no others. A value in which every entry is unusable is rejected.
languages query string no en,de,es,it,fr,pt,nl,sv,da,pl,no Comma-separated language codes. When omitted, the service uses en, de, es, it, fr, pt, nl, sv, da, pl and no. A code it does not accept is rejected.
min_confidence query number no 0 The lowest score to return, from 0 to 0.99. When omitted, 0. A value above 1 is read as 0.99. A value below 0 is read as 0. A value that is not a number is rejected.
fad_pref query string no - A prefix to apply. Repeat the parameter for more than one.
fad_suff query string no - A suffix to apply. Repeat the parameter for more than one.

Response fields

An example response
[
  {
    "Domain": "example.com",
    "Type": 0,
    "TLD": "com",
    "ConfidenceScore": 0.5,
    "Keys": [
      "example"
    ],
    "Variations": [],
    "Data": [
      {
        "Name": "length",
        "Data": 7
      },
      {
        "Name": "status",
        "Data": "ok"
      }
    ]
  }
]
NameTypeDescription
ConfidenceScore number How closely the suggestion matches what was asked. 1 when the score is 1 or higher, otherwise the score to three decimal places.
Data array Facts about the name. Each item has Name and Data. The names are length, keyscount, bad, dash, in_ga, idn and status.
Domain string The suggested domain name.
Keys array The keywords the suggestion was built from.
TLD string The top-level domain.
Type integer 1 when the suggestion is the exact name that was asked for, otherwise 0.
Variations array The variation codes applied to the name.

Errors

StatusWhat it means
200The names found. If the request runs out of time, this is still 200 and holds the names found before it stopped.
400A parameter the service cannot read, including a missing q, a func other than 3, a status it does not know, or the token sent twice.
401The token is missing, or it is not a token the service knows.
503The service is out of capacity.
429More than 10 requests a second, or a burst of more than 30, was refused.

POST /v5/fad

Suggest domain names, and also return the prefixes, suffixes, synonyms and top-level domains used.

Request

{
  "q": "locksmith",
  "authtoken": "YOUR_TOKEN",
  "fad_syn": {
    "lock": [
      "secure"
    ]
  }
}

Parameters

NameWhereTypeRequiredDefaultDescription
q body string yes - The words to suggest names from: a domain, a word or a phrase. Required. A query the service cannot use, or one longer than 63 characters after it is cleaned, is rejected.
authtoken body string yes - The access token for this account. The spelling authToken is also accepted. Send it once.
max_results body integer no 50 How many names to return. When omitted, the service uses 50, except when status is only reg, when it uses 10. A value above 200 is read as 200. A value that is not a positive whole number is rejected.
func body string no 0 Which names to produce. 0, the default, returns the exact name and variations on it. 1 returns the exact name only, and is what an omitted func is read as when no_suggestions is yes. 2 leaves the exact name out, and is what an omitted func is read as when only_suggestions is yes.
no_suggestions body string no - When this is yes and func is omitted, func is read as 1. 1, true or True means yes. Omitting it, or any other value, means no.
only_suggestions body string no - When this is yes and func is omitted, and no_suggestions is not yes, func is read as 2. 1, true or True means yes. Omitting it, or any other value, means no.
adult body string no - When this is yes, adult top-level domains may be included. 1, true or True means yes. Omitting it, or any other value, means no.
no_idn body string no - When this is yes, internationalized names are left out. 1, true or True means yes. Omitting it, or any other value, means no.
premium_ok body string no - When this is yes, premium names are included as well as the statuses asked for. 1, true or True means yes. Omitting it, or any other value, means no.
any_status body string no - When this is yes, every availability status is included. 1, true or True means yes. Omitting it, or any other value, means no.
status body array no - Which availability to return. Accepted values are ok, reg, pre and res. When omitted, ok. Repeat the parameter to ask for more than one. An unrecognised value is rejected. On POST /v5/fad, pass status as a list of these values.
custom_tlds body string no - Comma-separated top-level domains to use. A value in which every entry is unusable is rejected.
tld_ok body string no - Comma-separated top-level domains to allow in addition to the account's set. Entries the service cannot use are dropped.
tld_no body string no - Comma-separated top-level domains to leave out. Entries the service cannot use are dropped.
tld_only body string no - Comma-separated top-level domains to use and no others. A value in which every entry is unusable is rejected.
languages body string no en,de,es,it,fr,pt,nl,sv,da,pl,no Comma-separated language codes. When omitted, the service uses en, de, es, it, fr, pt, nl, sv, da, pl and no. A code it does not accept is rejected.
min_confidence body number no 0 The lowest score to return, from 0 to 0.99. When omitted, 0. A value above 1 is read as 0.99. A value below 0 is read as 0. A value that is not a number is rejected.
fad_pref body string no - A prefix to apply. Repeat the parameter for more than one.
fad_suff body string no - A suffix to apply. Repeat the parameter for more than one.
fad_syn body object no - An object mapping a word to a list of synonyms. Send it in the JSON body.

Response fields

An example response
{
  "suggestions": [
    {
      "Domain": "example.com",
      "Type": 0,
      "TLD": "com",
      "ConfidenceScore": 0.5,
      "Keys": [
        "example"
      ],
      "Variations": [],
      "Data": [
        {
          "Name": "length",
          "Data": 7
        },
        {
          "Name": "status",
          "Data": "ok"
        }
      ]
    }
  ],
  "FAD": [
    {
      "Name": "prefixes",
      "Data": []
    },
    {
      "Name": "suffixes",
      "Data": []
    },
    {
      "Name": "synonyms",
      "Data": {
        "lock": [
          "secure"
        ]
      }
    },
    {
      "Name": "tlds",
      "Data": [
        "com"
      ]
    }
  ]
}
NameTypeDescription
FAD array The prefixes, suffixes, synonyms and top-level domains used across the answer. Each item has Name and Data. The names are prefixes, suffixes, synonyms and tlds.
suggestions array The same name objects GET /v5/recommend returns. Each Data list also includes stamps.
ConfidenceScore number How closely the suggestion matches what was asked. 1 when the score is 1 or higher, otherwise the score to three decimal places.
Data array Facts about the name. Each item has Name and Data. The names are length, keyscount, bad, dash, in_ga, idn and status.
Domain string The suggested domain name.
Keys array The keywords the suggestion was built from.
TLD string The top-level domain.
Type integer 1 when the suggestion is the exact name that was asked for, otherwise 0.
Variations array The variation codes applied to the name.

Errors

StatusWhat it means
200The names found, with the prefixes, suffixes, synonyms and top-level domains used. If the request runs out of time, this is still 200 and holds what was found before it stopped.
400The body is not JSON, or a parameter the service cannot read, including a missing q or the token sent twice.
401The token is missing, or it is not a token the service knows.
503The service is out of capacity.
429More than 10 requests a second, or a burst of more than 30, was refused.

GET /v5/recommend

Suggest domain names from a word, a phrase or a name.

Request

GET /v5/recommend?q=locksmith&authtoken=YOUR_TOKEN

Parameters

NameWhereTypeRequiredDefaultDescription
q query string yes - The words to suggest names from: a domain, a word or a phrase. Required. A query the service cannot use, or one longer than 63 characters after it is cleaned, is rejected.
authtoken query string yes - The access token for this account. The spelling authToken is also accepted. Send it once.
max_results query integer no 50 How many names to return. When omitted, the service uses 50, except when status is only reg, when it uses 10. A value above 200 is read as 200. A value that is not a positive whole number is rejected.
func query string no 0 Which names to produce. 0, the default, returns the exact name and variations on it. 1 returns the exact name only, and is what an omitted func is read as when no_suggestions is yes. 2 leaves the exact name out, and is what an omitted func is read as when only_suggestions is yes.
no_suggestions query string no - When this is yes and func is omitted, func is read as 1. 1, true or True means yes. Omitting it, or any other value, means no.
only_suggestions query string no - When this is yes and func is omitted, and no_suggestions is not yes, func is read as 2. 1, true or True means yes. Omitting it, or any other value, means no.
adult query string no - When this is yes, adult top-level domains may be included. 1, true or True means yes. Omitting it, or any other value, means no.
no_idn query string no - When this is yes, internationalized names are left out. 1, true or True means yes. Omitting it, or any other value, means no.
premium_ok query string no - When this is yes, premium names are included as well as the statuses asked for. 1, true or True means yes. Omitting it, or any other value, means no.
any_status query string no - When this is yes, every availability status is included. 1, true or True means yes. Omitting it, or any other value, means no.
status query string no ok Which availability to return. Accepted values are ok, reg, pre and res. When omitted, ok. Repeat the parameter to ask for more than one. An unrecognised value is rejected. On POST /v5/fad, pass status as a list of these values.
custom_tlds query string no - Comma-separated top-level domains to use. A value in which every entry is unusable is rejected.
tld_ok query string no - Comma-separated top-level domains to allow in addition to the account's set. Entries the service cannot use are dropped.
tld_no query string no - Comma-separated top-level domains to leave out. Entries the service cannot use are dropped.
tld_only query string no - Comma-separated top-level domains to use and no others. A value in which every entry is unusable is rejected.
languages query string no en,de,es,it,fr,pt,nl,sv,da,pl,no Comma-separated language codes. When omitted, the service uses en, de, es, it, fr, pt, nl, sv, da, pl and no. A code it does not accept is rejected.
min_confidence query number no 0 The lowest score to return, from 0 to 0.99. When omitted, 0. A value above 1 is read as 0.99. A value below 0 is read as 0. A value that is not a number is rejected.
fad_pref query string no - A prefix to apply. Repeat the parameter for more than one.
fad_suff query string no - A suffix to apply. Repeat the parameter for more than one.

Response fields

An example response
[
  {
    "Domain": "example.com",
    "Type": 0,
    "TLD": "com",
    "ConfidenceScore": 0.5,
    "Keys": [
      "example"
    ],
    "Variations": [],
    "Data": [
      {
        "Name": "length",
        "Data": 7
      },
      {
        "Name": "status",
        "Data": "ok"
      }
    ]
  }
]
NameTypeDescription
ConfidenceScore number How closely the suggestion matches what was asked. 1 when the score is 1 or higher, otherwise the score to three decimal places.
Data array Facts about the name. Each item has Name and Data. The names are length, keyscount, bad, dash, in_ga, idn and status.
Domain string The suggested domain name.
Keys array The keywords the suggestion was built from.
TLD string The top-level domain.
Type integer 1 when the suggestion is the exact name that was asked for, otherwise 0.
Variations array The variation codes applied to the name.

Errors

StatusWhat it means
200The names found. If the request runs out of time, this is still 200 and holds the names found before it stopped.
400A parameter the service cannot read: a missing q, a status it does not know, a max_results or min_confidence that is not a number, a language it does not accept, custom_tlds or tld_only in which every top-level domain is unusable, or the token sent twice.
401The token is missing, or it is not a token the service knows.
503The service is out of capacity.
429More than 10 requests a second, or a burst of more than 30, was refused.

GET /v5/tlds

List the top-level domains the service can use. Each value is zone or meta. This request needs no token.

Request

GET /v5/tlds

Parameters

This request takes no parameters.

Response fields

An example response
{
  "tlds": {
    "com": "zone"
  }
}
NameTypeDescription
tlds object Each top-level domain the service can use, mapped to zone or meta.

Errors

StatusWhat it means
200The top-level domains, each marked zone or meta.
429More than 10 requests a second, or a burst of more than 30, was refused.