# Search domain availability (https://developer.godaddy.com/en/docs/api-users/search-domains) ## 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: <> ```bash curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js 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); ``` ```python 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"]) ``` ```go 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: ```json { "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. Prices from availability checks are indicative. The authoritative price is locked when you call `POST /v3/domains/registration-quotes`. Go to [Register a domain](https://developer.godaddy.com/docs/api-users/purchase-domains/register) for the full quote-execute flow. Reference: [`GET /v3/domains/check-availability`](https://developer.godaddy.com/docs/references/rest/domains/v3/discovery) ### 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: <> ```bash curl -s "https://api.godaddy.com/v3/domains/suggestions?query=sunrise+bakery&tlds=com,net,shop&pageSize=10" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js 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)); ``` ```python 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"]) ``` ```go 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: ```json { "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`](https://developer.godaddy.com/docs/references/rest/domains/v3/discovery) ## Use the CLI After you [set up the CLI](https://developer.godaddy.com/docs/api-users/cli-setup), 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: ```bash 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 10 ``` ## Read 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