Search domain availability
View as MarkdownCheck whether a domain is available to register, or get natural-language suggestions for alternatives. Both operations are available through the v3 API.
Overview
Search operations let you check whether a specific domain is available for registration, and discover alternative names based on keywords or natural-language queries. Both operations are read-only, require no payment method, and return indicative pricing alongside results.
v3 (recommended)
v3 offers two discovery operations: a single-domain availability check and a suggestions endpoint that returns available alternatives for a natural-language query.
Check availability
GET /v3/domains/check-availability?domain={domain} returns availability and per-term pricing for a single domain.
The following procedure checks whether a domain is available to register.
- Run the following command for your preferred language:
curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \
-H "Authorization: Bearer $GODADDY_PAT"const pat = process.env.GODADDY_PAT;
const url = new URL("https://api.godaddy.com/v3/domains/check-availability");
url.searchParams.set("domain", "your-idea.com");
const res = await fetch(url, {
headers: { Authorization: `Bearer ${pat}` },
});
const result = await res.json();
console.log(result.available, result.prices?.[0]?.price);import os, requests
pat = os.environ["GODADDY_PAT"]
res = requests.get(
"https://api.godaddy.com/v3/domains/check-availability",
params={"domain": "your-idea.com"},
headers={"Authorization": f"Bearer {pat}"},
)
data = res.json()
print(data["available"], data["prices"][0]["price"])package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
pat := os.Getenv("GODADDY_PAT")
req, _ := http.NewRequest("GET",
"https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com", nil)
req.Header.Set("Authorization", "Bearer "+pat)
res, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer res.Body.Close()
var result struct {
Available bool `json:"available"`
Prices []map[string]any `json:"prices"`
}
json.NewDecoder(res.Body).Decode(&result)
fmt.Println(result.Available, result.Prices)
}| Parameter | Required | Description | Note |
|---|---|---|---|
domain | Yes | Fully-qualified domain name to check. | IDN values must be in punycode A-label form. |
optimizeFor | No | SPEED (default, cached) or ACCURACY (live registry check, higher latency). | Availability is always re-verified at quote time regardless of this setting. |
iscCode | No | ISC discount code for pricing context. | When provided, prices reflect the applicable rates for this ISC. |
Response includes availability and indicative per-term pricing:
{
"domain": "your-idea.com",
"available": true,
"definitive": false,
"inventory": "REGISTRY",
"prices": [
{ "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } },
{ "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 } }
]
}prices[] contains one entry per available registration term. All price values are in cents.
Indicative pricing
Prices from availability checks are indicative. The authoritative price is locked when you call POST /v3/domains/registration-quotes. Go to Register a domain for the full quote-execute flow.
Reference: GET /v3/domains/check-availability
Get suggestions
GET /v3/domains/suggestions returns available domain name suggestions for a natural-language query or keyword set. All results are available without filtering required.
The following procedure gets domain name suggestions for a query.
- Run the following command for your preferred language:
curl -s "https://api.godaddy.com/v3/domains/suggestions?query=sunrise+bakery&tlds=com,net,shop&pageSize=10" \
-H "Authorization: Bearer $GODADDY_PAT"const pat = process.env.GODADDY_PAT;
const url = new URL("https://api.godaddy.com/v3/domains/suggestions");
url.searchParams.set("query", "sunrise bakery");
url.searchParams.set("tlds", "com,net,shop");
url.searchParams.set("pageSize", "10");
const res = await fetch(url, {
headers: { Authorization: `Bearer ${pat}` },
});
const { items } = await res.json();
items.forEach((item) => console.log(item.domain, item.prices?.[0]?.price));import os, requests
pat = os.environ["GODADDY_PAT"]
res = requests.get(
"https://api.godaddy.com/v3/domains/suggestions",
params={"query": "sunrise bakery", "tlds": "com,net,shop", "pageSize": 10},
headers={"Authorization": f"Bearer {pat}"},
)
for item in res.json()["items"]:
print(item["domain"], item["prices"][0]["price"])package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"os"
)
func main() {
pat := os.Getenv("GODADDY_PAT")
u, _ := url.Parse("https://api.godaddy.com/v3/domains/suggestions")
q := u.Query()
q.Set("query", "sunrise bakery")
q.Set("tlds", "com,net,shop")
q.Set("pageSize", "10")
u.RawQuery = q.Encode()
req, _ := http.NewRequest("GET", u.String(), nil)
req.Header.Set("Authorization", "Bearer "+pat)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
var body struct {
Items []struct{ Domain string `json:"domain"` } `json:"items"`
}
json.NewDecoder(res.Body).Decode(&body)
for _, item := range body.Items {
fmt.Println(item.Domain)
}
}| Parameter | Required | Description | Note |
|---|---|---|---|
query | No | Natural-language query or keywords. | For example, sunrise bakery. |
tlds | No | Comma-separated TLDs to include. | For example, com,net,shop. |
pageSize | No | Number of suggestions to return. | 1–50, default 10. |
lengthMin | No | Minimum second-level domain length. | |
lengthMax | No | Maximum second-level domain length. | |
sources | No | Comma-separated suggestion strategies: EXTENSION (vary TLD), KEYWORD_SPIN (rotate keywords), CC_TLD (country-code TLDs), PREMIUM (include premium-priced names). |
Response is an object with an items array. Each entry includes the domain name and indicative per-term pricing:
{
"items": [
{
"domain": "sunrisebakery.com",
"inventory": "REGISTRY",
"prices": [
{ "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }
]
}
]
}price.value and renewalPrice.value are in cents — divide by 100 for the display price.
Reference: GET /v3/domains/suggestions
Use the CLI
After you set up the CLI, you can use it to check single-domain availability and get domain suggestions.
The following procedure checks availability and gets suggestions using the CLI.
- Run the command for your operation:
gddy domain available your-idea.com
gddy domain available your-idea.com --check-type full
gddy domain suggest "your idea" --tlds com --tlds app --limit 10Read the response
Price fields return a {currencyCode, value} object. value is an integer in cents — divide by 100 for the display price. For example, {"currencyCode": "USD", "value": 1199} displays as $11.99.
Common errors
| Status | Most likely cause |
|---|---|
400 | Malformed request — domain missing, not a valid FQDN, or invalid query parameter. |
401 | Authentication credentials are missing or invalid. |
403 | Caller is not authorized. Check that your token includes the domains.domain:read scope. |
429 | Rate limit exceeded. Honor the Retry-After header before retrying. |
5xx | Upstream registry timeout. Safe to retry — availability checks are idempotent. |
Additional information
Purchase a domain
Use the v3 quote-execute flow to lock a price and register.
v3 Discovery reference
Full check-availability and suggestions endpoint docs.
Agent & Automation Notes
domains.domain:readRelated
API References
Concepts
Last updated on
How is this guide?