Guides
Guides

lookup (domain)

Determines the availability of a specified domain name.

Suggest Edits

Request parameters

Standard request parameters

  • action = lookup
  • object = domain
  • registrant_ip = valid IP address of the registrant (optional)

Request attributes

Parameters within the attributes associative array are described below:

ParameterObligationDefinition/Value
domainRequiredThe domain name to be queried.
no_cacheOptionalIn order to obtain results quickly, the default for the lookup command is to check the local OpenSRS cache to determine domain name availability.

If you specify no_cache = 1, instead of checking the cache, the lookup command queries the applicable registry to determine domain name availability.

Note: Setting no_cache to 1 increases the amount of time it takes to get results.

Response parameters

Standard response parameters

  • action = reply
  • object = domain
  • is_success = Boolean indicating success or failure of the request.
  • response_code = Response code indicating outcome of the request.
  • response_text = Message describing the outcome of the request.

📘

Note

If the domain being queried is taken (response_code = 211), is_success is set to 1 because the query was successful. Therefore, be sure to check the response_code and response_text when reading the reply.

Response attributes

If the request is successful, the attributes associative array may include the following:

ParameterObligationDefinition/Value
statusAlways returnedWhether the domain is available or taken.
price_statusAlways returnedThe pricing status.
Undef—Non .TV domains
Fixed—Price is fixed for .TV domains.
has_claimReturned for new TLDs during the claim periodIndicates whether the domain name has a matching mark registered at the Trademark Clearinghouse (TMCH).
0—No matching marks exist at the TMCH.
1—A mark is registered at the TMCH that matches the domain name.
email_availableReturned for .NAME domainsIndicates whether a forwarding email is available or not.
Applies to .NAME domains only.
0—No forwarding email available
1—Forwarding email available
noserviceReturned for .NAME domainsIndicates Registry Agent availability. If RA is available, noservice does not appear in response.
1—Supplier unavailable

Note: when noservice = 1, is_success = 0.

Registry Premium Domain

📘

Note

Querying a registry premium domain will always generate a taken response if the reseller has not enabled the registry premium tier to which the domain belongs.

If the request is successful and the domain is a registry premium domain, the attributes associative array will also include:

ParameterObligationDefinition/Value
reasonAlways returnedIndicates that the domain is registry premium. Value if returned: Premium Name.

Examples

Standard lookup

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="action">LOOKUP</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="domain">example.com</item>
                        <item key="no_cache">1</item>
                    </dt_assoc>
                </item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="response_text">Domain available</item>
                <item key="action">REPLY</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="price_status">undef</item>
                        <item key="email_available">undef</item>
                        <item key="status">available</item>
                    </dt_assoc>
                </item>
                <item key="response_code">210</item>
                <item key="is_success">1</item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="response_text">Domain taken</item>
                <item key="action">REPLY</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="price_status">undef</item>
                        <item key="email_available">undef</item>
                        <item key="status">taken</item>
                    </dt_assoc>
                </item>
                <item key="response_code">211</item>
                <item key="is_success">1</item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

New TLD lookup during the claims period.

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="action">LOOKUP</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="domain">example.guru</item>
                    </dt_assoc>
                </item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="response_text">Domain available</item>
                <item key="action">REPLY</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="status">available</item>
                        <item key="has_claim">1</item>
                    </dt_assoc>
                </item>
                <item key="response_code">210</item>
                <item key="is_success">1</item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

Premium domain lookup

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="action">LOOKUP</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="domain">ddd.bike</item>
                    </dt_assoc>
                </item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="response_text">Domain available</item>
                <item key="action">REPLY</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="status">available</item>
                        <item key="reason">Premium Name</item>
                    </dt_assoc>
                </item>
                <item key="response_code">210</item>
                <item key="is_success">1</item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

<?xml version='1.0' encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
    <header>
        <version>0.9</version>
    </header>
    <body>
        <data_block>
            <dt_assoc>
                <item key="protocol">XCP</item>
                <item key="object">DOMAIN</item>
                <item key="response_text">Domain taken</item>
                <item key="action">REPLY</item>
                <item key="attributes">
                    <dt_assoc>
                        <item key="status">taken</item>
                        <item key="reason">Premium Name</item>
                    </dt_assoc>
                </item>
                <item key="response_code">211</item>
                <item key="is_success">1</item>
            </dt_assoc>
        </data_block>
    </body>
</OPS_envelope>

Updated almost 2 years ago