Python wrapper for the DomainTools API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

domaintoolsAPI PYTHON Wrapper


The domaintoolsAPI PYTHON Wrapper is a simple connector to access all webservices of

Getting started

1- Clone the project with Git by running:

$ git clone git://

2- In domaintools/conf/, rename the api.ini.default to api.ini

3- Fill api.ini with your domaintools credentials:

username  = 'your_api_username';
key       = 'your_api_key';

3-A Create a short PYTHON file to make a simple call to a webservice (whois for example):

  from domaintools.api.request import Request

  # Make a call to the webservice whois with a xml return
  # type for the domain name :

  # prepare request
  request  = Request().service("whois").withType("xml").domain("")

  # call request
  response = request.execute()

  # display response
  print response

3-B If added you can also override on the fly your configuration :

  from domaintools.api.request       import Request
  from domaintools.api.configuration import Configuration

  # from the default configuration, we change some values
  configuration = Configuration({'username':'username', 'password':'password'});

  # Make a call to the webservice whois with a xml return
  # type for the domain name :

  request  = Request(configuration).service("whois").withType("xml").domain("")
  response = request.execute()

  # Display the response
  print response

4- Execute the PYTHON script:

$ python

If everything works fine, you should have a display like this:

<?xml version="1.0"?>
    <registrant>DomainTools, LLC</registrant>
      <record>Domain name:

      Registrant Contact:
         DomainTools, LLC
         Domain Administrator (
         Fax: +1.2068389056
         2211 5th Avenue
         Suite 201
         Seattle, WA 98121

      Administrative Contact:
         DomainTools, LLC
         Domain Administrator (
         Fax: +1.2068389056
         2211 5th Avenue
         Suite 201
         Seattle, WA 98121

      Technical Contact:
         DomainTools, LLC
         Domain Administrator (
         Fax: +1.2068389056
         2211 5th Avenue
         Suite 201
         Seattle, WA 98121

         Status: Active
         Creation Date: 13-Jul-2002
         Expiration Date: 13-Jul-2016
         Name Server: NS1.P09.DYNECT.NET
         Name Server: NS2.P09.DYNECT.NET
         Name Server: NS3.P09.DYNECT.NET
         Name Server: NS4.P09.DYNECT.NET

5- Read the documentation to learn more, and visit to know the list of available services.

Quick examples

In the main directory, you shoud have some examples to quickly test the API :



The domaintoolsAPI PYTHON Wrapper is a fluent API implemented by using method chaining.

After having instanciate your request like this:

request = Request()

You can combine methods to specify return type, options, etc.:

print request.service('mark-alert').where({"query":"domaintools"}).withType("xml").execute()

Choose service to call - service


If no service is found the default service called will be Domain Profile. You can find the list of available services on

Specify options - where

request.service("mark-alert").where({"query":"domain tools"})

The method where allows to specify options of the service. It takes only on parameter, a dictionary of options where the key is the name of the option and value is the value of the option.

The list of options for each service is available on the domaintoolsAPI documentation .

Specify return type - withType


The method withType allows to specify the return type of the response. It takes only one parameter, the name of the return type.

The list of return types is available on the domaintoolsAPI documentation.

You can also use toJson, toXml and toHtml as aliases of withType :

  print request.service("whois").domain('').toJson().execute() # json
  print request.service("whois").domain('').toXml().execute()  # xml
  print request.service("whois").domain('').toHtml().execute() # html

If no return type, a Response object is returned

By default (If you don't call the method withType) the return type used is a Response object:

  response = request.service("whois").domain('').execute()

With this response object, you will be able to access to response properties :

  response = request.service("whois").domain('').execute()

  print response.registrant # Domaintools, LLC

  print # 2011-10-17

Call the service - execute

  response = request.service("whois").domain("").execute()

To call the service use the method execute, and return the response.

The response is a string with the format of the specify return type (JSON or XML for example).

Tests with minimock

Here is the procedure to test this API

1- Install Minimock

2- Go into the main directory containing

2- Call all tests once (in console) :


In domaintools/tests/ are included all the tests classes. You should have a similar result :

Ran 17 tests in 0.004s



See the file for details.


Copyright (C) 2011 by, DomaintoolsAPI PYTHON Wrapper is released under the MIT license. See the file for details.