Skip to main content

DomainTools' Official Python API

Project description

domaintools

PyPI version Build Status Coverage Status License

DomainTools’ Official Python API

domaintools Example

domaintools Example

Installing the DomainTools’ API

To install the API run

pip install domaintools_api --upgrade

Ideally, within a virtual environment.

Using the API

To start out create an instance of the API - passing in your credentials

from domaintools import API


api = API(USER_NAME, KEY)

Every API endpoint is then exposed as a method on the API object, with any parameters that should be passed into that endpoint being passed in as method arguments:

api.domain_search('google', exclude='photos')

You can get an overview of every endpoint that you can interact with using the builtin help function:

help(api)

If applicable, native Python looping can be used directly to loop through any results:

for result in api.domain_search('google', exclude='photos'):
    print(result['sld'])

You can also use a context manager to ensure processing on the results only occurs if the request is successfully made:

with api.domain_search('google', exclude='photos') as results:
    print(results)

For API calls where a single item is expected to be returned, you can directly interact with the result:

profile = api.domain_profile('google.com')
title = profile['website_data']['title']

For any API call where a single type of data is expected you can directly cast to the desired type:

float(api.reputation('google.com')) == 0.0
int(api.reputation('google.com')) == 0

The entire structure returned from DomainTools can be retrieved by doing .data() while just the actionable response information can be retrieved by doing .response():

api.domain_search('google').data() == {'response': { ... }}
api.domain_search('google').response() == { ... }

You can directly get the html, xml, or json version of the response by calling .(html|xml|json)():

html = str(api.domain_search('google').json())
xml = str(api.domain_search('google').xml())
html = str(api.domain_search('google').html())

If any API call is unsuccesfull, one of the exceptions defined in domaintools.exceptions will be raised:

api.domain_profile('notvalid').data()


---------------------------------------------------------------------------
BadRequestException                       Traceback (most recent call last)
<ipython-input-3-f9e22e2cf09d> in <module>()
----> 1 api.domain_profile('google').data()

/home/tcrosley/projects/external/python_api/venv/lib/python3.5/site-packages/domaintools-0.0.1-py3.5.egg/domaintools/base_results.py in data(self)
     25                 self.api._request_session = Session()
     26             results = self.api._request_session.get(self.url, params=self.kwargs)
---> 27             self.status = results.status_code
     28             if self.kwargs.get('format', 'json') == 'json':
     29                 self._data = results.json()

/home/tcrosley/projects/external/python_api/venv/lib/python3.5/site-packages/domaintools-0.0.1-py3.5.egg/domaintools/base_results.py in status(self, code)
     44
     45         elif code == 400:
---> 46             raise BadRequestException()
     47         elif code == 403:
     48             raise NotAuthorizedException()

BadRequestException:

the exception will contain the status code and the reason for the exception:

try:
    api.domain_profile('notvalid').data()
except Exception as e:
    assert e.code == 400
    assert 'We could not understand your request' in e.reason['error']['message']

You can get the status code of a response outside of exception handling by doing .status:

api.domain_profile('google.com').status == 200

Using the API Asynchronously

domaintools Async Example

domaintools Async Example

If you are running on Python 3.5+ the DomainTools’ API automatically supports async usage:

search_results = await api.domain_search('google')

There is built-in support for async context managers:

async with api.domain_search('google') as search_results:
    # do things

And direct async for loops:

async for result in api.domain_search('google'):
    print(result)

All async operations can safely be intermixed with non async ones - with optimal performance achieved if the async call is done first:

profile = api.domain_profile('google.com')
await profile
title = profile['website_data']['title']

Interacting with the API via the command line client

domaintools CLI Example

domaintools CLI Example

Immediately after installing domaintools_api with pip, a domaintools command line client will become available to you:

domaintools --help

To use - simply pass in the api_call you would like to make along with the parameters that it takes and your credentials:

domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY

Optionally, you can specify the desired format (html, xml, json, or list) of the results:

domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY -f html

To avoid having to type in your API key repeatedly, you can specify them in ~/.dtapi separated by a new line:

API_USER
API_KEY

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

domaintools_api-0.2.4.tar.gz (15.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page