# Search domain availability (https://developer.godaddy.com/en/docs/api-users/search-domains)

***

title: Search domain availability
description: Check whether a domain is available to register, or get natural-language suggestions for alternatives. Both operations are available through the v3 API.
agentNotes:
permissions: \["Domain Search"]
scopes: \["domains.domain:read"]
idempotent: true
destructive: false
failureRecovery: "Safe to retry on any error. Results are cached; use optimizeFor=ACCURACY for live registry checks."
related:
apis:

* title: "Domains v3 — Discovery"
  href: "/docs/references/rest/domains/v3/discovery"
  guides:
* title: "Register a domain"
  href: "/docs/api-users/purchase-domains/register"
* title: "Manage DNS records"
  href: "/docs/api-users/manage-domains/dns"
  concepts:
* title: "Authentication"
  href: "/docs/api-users/auth"
* title: "Rate limits"
  href: "/docs/api-users/rate-limits"

***

## 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 tab="curl"
curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

```js tab="Node"
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 tab="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 tab="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 tab="curl"
curl -s "https://api.godaddy.com/v3/domains/suggestions?query=sunrise+bakery&tlds=com,net,shop&pageSize=10" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

```js tab="Node"
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 tab="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 tab="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