Skip to main content

DomainTools' Official Python API

Project description

|domaintools|
=============

|PyPI version| |Build Status| |Coverage Status| |License| |Join the chat
at https://gitter.im/DomainTools/python\_api|

DomainTools' Official Python API

.. figure:: https://github.com/DomainTools/python_api/raw/master/artwork/example.gif
:alt: domaintools Example

domaintools Example

Installing the DomainTools' API
===============================

To install the API run

.. code:: bash

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

.. code:: python


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:

.. code:: python

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

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

.. code:: python

help(api)

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

.. code:: python

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:

.. code:: python

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:

.. code:: python

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:

.. code:: python

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()``:

.. code:: python

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)()``:

.. code:: python

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:

.. code:: python

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:

.. code:: python

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``:

.. code:: python


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

Using the API Asynchronously
============================

.. figure:: https://github.com/DomainTools/python_api/raw/master/artwork/example_async.gif
:alt: domaintools Async Example

domaintools Async Example

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

.. code:: python


search_results = await api.domain_search('google')

There is built-in support for async context managers:

.. code:: python

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

And direct async for loops:

.. code:: python

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:

.. code:: python

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

Interacting with the API via the command line client
====================================================

.. figure:: https://github.com/DomainTools/python_api/raw/master/artwork/example_cli.gif
:alt: domaintools CLI Example

domaintools CLI Example

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

.. code:: bash

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:

.. code:: bash

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:

.. code:: bash

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:

.. code:: bash

API_USER
API_KEY

.. |domaintools| image:: https://github.com/DomainTools/python_api/raw/master/artwork/logo.png
.. |PyPI version| image:: https://badge.fury.io/py/domaintools_api.svg
:target: http://badge.fury.io/py/domaintools
.. |Build Status| image:: https://travis-ci.org/DomainTools/python_api.svg?branch=master
:target: https://travis-ci.org/DomainTools/python_api
.. |Coverage Status| image:: https://coveralls.io/repos/github/DomainTools/python_api/badge.svg?branch=master
:target: https://coveralls.io/github/DomainTools/python_api?branch=master
.. |License| image:: https://img.shields.io/github/license/mashape/apistatus.svg
:target: https://pypi.python.org/pypi/domaintools_api/
.. |Join the chat at https://gitter.im/DomainTools/python\_api| image:: https://badges.gitter.im/Join%20Chat.svg
:target: https://gitter.im/DomainTools/python_api?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

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.1.5.tar.gz (12.4 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