| Name | domaintools-api-v2 JSON |
| Version |
2.0.1
JSON |
| download |
| home_page | None |
| Summary | DomainTools Official Python API |
| upload_time | 2024-05-09 16:27:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | The MIT License (MIT) Copyright (c) 2016 DomainTools Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
python
python3
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
===================
[](http://badge.fury.io/py/domaintools_api)
[](https://github.com/domaintools/python_api/actions)
[](https://coveralls.io/github/DomainTools/python_api?branch=main)
[](https://pypi.python.org/pypi/domaintools_api/)
DomainTools Official Python API
The DomainTools Python API Wrapper provides an interface to work with our cybersecurity and related data tools provided by our Iris Investigate™, Iris Enrich™, and Iris Detect™ products. It is actively maintained and may be downloaded via <a href="https://github.com/DomainTools/python_api">GitHub</a> or <a href="https://pypi.org/project/domaintools-api/">PyPI</a>. See the included README file, the examples folder, and API documentation (https://app.swaggerhub.com/apis-docs/DomainToolsLLC/DomainTools_APIs/1.0#) for more info.
Installing the DomainTools API
===================
To install the API run
```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
```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:
```python
api.iris_enrich('domaintools.com')
```
You can get an overview of every endpoint that you can interact with using the builtin help function:
```python
help(api)
```
Or if you know the endpoint you want to use, you can get more information about it:
```python
help(api.iris_investigate)
```
If applicable, native Python looping can be used directly to loop through any results:
```python
for result in api.iris_enrich('domaintools.com').response().get('results', {}):
print(result['domain'])
```
You can also use a context manager to ensure processing on the results only occurs if the request is successfully made:
```python
with api.iris_enrich('domaintools.com').response().get('results', {}) as results:
print(results)
```
For API calls where a single item is expected to be returned, you can directly interact with the result:
```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:
```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()`:
```python
api.iris_enrich('domaintools.com').data() == {'response': { ... }}
api.iris_enrich('domaintools.com').response() == { ... }
```
You can directly get the html, xml, or json version of the response by calling `.(html|xml|json)()` These only work with non AsyncResults:
```python
json = 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:
```python-traceback
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:
```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`:
```python
api.domain_profile('google.com').status == 200
```
Using the API Asynchronously
===================
The DomainTools API automatically supports async usage:
```python
search_results = await api.iris_enrich('domaintools.com').response().get('results', {})
```
There is built-in support for async context managers:
```python
async with api.iris_enrich('domaintools.com').response().get('results', {}) as search_results:
# do things
```
And direct async for loops:
```python
async for result in api.iris_enrich('domaintools.com').response().get('results', {}):
print(result)
```
All async operations can safely be intermixed with non async ones - with optimal performance achieved if the async call is done first:
```python
profile = api.domain_profile('google.com')
await profile
title = profile['website_data']['title']
```
Interacting with the API via the command line client
===================
Immediately after installing `domaintools_api` with pip, a `domaintools` command line client will become available to you:
```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:
```bash
domaintools iris_investigate --domains domaintools.com -u $TEST_USER -k $TEST_KEY
```
Optionally, you can specify the desired format (html, xml, json, or list) of the results:
```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:
```bash
API_USER
API_KEY
```
Python Version Support Policy
===================
Please see the [supported versions](https://github.com/DomainTools/python_api/raw/main/PYTHON_SUPPORT.md) document
for the DomainTools Python support policy.
Raw data
{
"_id": null,
"home_page": null,
"name": "domaintools-api-v2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Python, Python3",
"author": null,
"author_email": "DomainTools <integrations@domaintools.com>",
"download_url": "https://files.pythonhosted.org/packages/91/8d/1de01a01a254f13cf7d4a9963c20ce5ec7c269768f52bf7286ecf9d5d9c3/domaintools_api_v2-2.0.1.tar.gz",
"platform": null,
"description": "\n===================\n\n[](http://badge.fury.io/py/domaintools_api)\n[](https://github.com/domaintools/python_api/actions)\n[](https://coveralls.io/github/DomainTools/python_api?branch=main)\n[](https://pypi.python.org/pypi/domaintools_api/)\n\nDomainTools Official Python API\n\n\n\nThe DomainTools Python API Wrapper provides an interface to work with our cybersecurity and related data tools provided by our Iris Investigate\u2122, Iris Enrich\u2122, and Iris Detect\u2122 products. It is actively maintained and may be downloaded via <a href=\"https://github.com/DomainTools/python_api\">GitHub</a> or <a href=\"https://pypi.org/project/domaintools-api/\">PyPI</a>. See the included README file, the examples folder, and API documentation (https://app.swaggerhub.com/apis-docs/DomainToolsLLC/DomainTools_APIs/1.0#) for more info.\n\nInstalling the DomainTools API\n===================\n\nTo install the API run\n\n```bash\npip install domaintools_api --upgrade\n```\n\nIdeally, within a virtual environment.\n\n\nUsing the API\n===================\n\nTo start out create an instance of the API - passing in your credentials\n\n```python\n\nfrom domaintools import API\n\n\napi = API(USER_NAME, KEY)\n```\n\nEvery API endpoint is then exposed as a method on the API object, with any parameters that should be passed into that endpoint\nbeing passed in as method arguments:\n\n```python\napi.iris_enrich('domaintools.com')\n```\n\nYou can get an overview of every endpoint that you can interact with using the builtin help function:\n\n```python\nhelp(api)\n```\n\nOr if you know the endpoint you want to use, you can get more information about it:\n\n```python\nhelp(api.iris_investigate)\n```\n\nIf applicable, native Python looping can be used directly to loop through any results:\n\n```python\nfor result in api.iris_enrich('domaintools.com').response().get('results', {}):\n print(result['domain'])\n```\n\nYou can also use a context manager to ensure processing on the results only occurs if the request is successfully made:\n\n```python\nwith api.iris_enrich('domaintools.com').response().get('results', {}) as results:\n print(results)\n```\n\nFor API calls where a single item is expected to be returned, you can directly interact with the result:\n\n```python\nprofile = api.domain_profile('google.com')\ntitle = profile['website_data']['title']\n```\n\nFor any API call where a single type of data is expected you can directly cast to the desired type:\n\n```python\nfloat(api.reputation('google.com')) == 0.0\nint(api.reputation('google.com')) == 0\n```\n\nThe entire structure returned from DomainTools can be retrieved by doing `.data()` while just the actionable response information\ncan be retrieved by doing `.response()`:\n\n```python\napi.iris_enrich('domaintools.com').data() == {'response': { ... }}\napi.iris_enrich('domaintools.com').response() == { ... }\n```\n\nYou can directly get the html, xml, or json version of the response by calling `.(html|xml|json)()` These only work with non AsyncResults:\n```python\njson = str(api.domain_search('google').json())\nxml = str(api.domain_search('google').xml())\nhtml = str(api.domain_search('google').html())\n```\n\nIf any API call is unsuccesfull, one of the exceptions defined in `domaintools.exceptions` will be raised:\n\n```python-traceback\napi.domain_profile('notvalid').data()\n\n\n---------------------------------------------------------------------------\nBadRequestException Traceback (most recent call last)\n<ipython-input-3-f9e22e2cf09d> in <module>()\n----> 1 api.domain_profile('google').data()\n\n/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)\n 25 self.api._request_session = Session()\n 26 results = self.api._request_session.get(self.url, params=self.kwargs)\n---> 27 self.status = results.status_code\n 28 if self.kwargs.get('format', 'json') == 'json':\n 29 self._data = results.json()\n\n/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)\n 44\n 45 elif code == 400:\n---> 46 raise BadRequestException()\n 47 elif code == 403:\n 48 raise NotAuthorizedException()\n\nBadRequestException:\n\n```\n\nthe exception will contain the status code and the reason for the exception:\n\n```python\ntry:\n api.domain_profile('notvalid').data()\nexcept Exception as e:\n assert e.code == 400\n assert 'We could not understand your request' in e.reason['error']['message']\n```\n\nYou can get the status code of a response outside of exception handling by doing `.status`:\n\n```python\n\napi.domain_profile('google.com').status == 200\n```\n\nUsing the API Asynchronously\n===================\n\n\n\nThe DomainTools API automatically supports async usage:\n\n```python\n\nsearch_results = await api.iris_enrich('domaintools.com').response().get('results', {})\n```\n\nThere is built-in support for async context managers:\n\n```python\nasync with api.iris_enrich('domaintools.com').response().get('results', {}) as search_results:\n # do things\n```\n\nAnd direct async for loops:\n\n```python\nasync for result in api.iris_enrich('domaintools.com').response().get('results', {}):\n print(result)\n```\n\nAll async operations can safely be intermixed with non async ones - with optimal performance achieved if the async call is done first:\n```python\nprofile = api.domain_profile('google.com')\nawait profile\ntitle = profile['website_data']['title']\n```\n\nInteracting with the API via the command line client\n===================\n\n\n\nImmediately after installing `domaintools_api` with pip, a `domaintools` command line client will become available to you:\n\n```bash\ndomaintools --help\n```\n\nTo use - simply pass in the api_call you would like to make along with the parameters that it takes and your credentials:\n\n```bash\ndomaintools iris_investigate --domains domaintools.com -u $TEST_USER -k $TEST_KEY\n```\n\nOptionally, you can specify the desired format (html, xml, json, or list) of the results:\n\n```bash\ndomaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY -f html\n```\n\nTo avoid having to type in your API key repeatedly, you can specify them in `~/.dtapi` separated by a new line:\n\n```bash\nAPI_USER\nAPI_KEY\n```\n\nPython Version Support Policy\n===================\n\nPlease see the [supported versions](https://github.com/DomainTools/python_api/raw/main/PYTHON_SUPPORT.md) document \nfor the DomainTools Python support policy.\n",
"bugtrack_url": null,
"license": "The MIT License (MIT) Copyright (c) 2016 DomainTools Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "DomainTools Official Python API",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://github.com/domaintools/python_api"
},
"split_keywords": [
"python",
" python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f679ebe46ccddcedf62b8d5674c215b99f80facd97ca3d22703d133058359aed",
"md5": "b5e8ef1fb12b6eb8a5feb3490f6741fe",
"sha256": "814046e49d2ee6424f360f0d5e448471e67cb8f3ca9866fd52922a29baf118c9"
},
"downloads": -1,
"filename": "domaintools_api_v2-2.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5e8ef1fb12b6eb8a5feb3490f6741fe",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 38269,
"upload_time": "2024-05-09T16:27:40",
"upload_time_iso_8601": "2024-05-09T16:27:40.985247Z",
"url": "https://files.pythonhosted.org/packages/f6/79/ebe46ccddcedf62b8d5674c215b99f80facd97ca3d22703d133058359aed/domaintools_api_v2-2.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "918d1de01a01a254f13cf7d4a9963c20ce5ec7c269768f52bf7286ecf9d5d9c3",
"md5": "26fe465057787f09c5b62810b14ecd81",
"sha256": "41a330ee943aece657d42e5c8f2588109aa8a91917b2c7400eb269be573ed3b1"
},
"downloads": -1,
"filename": "domaintools_api_v2-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "26fe465057787f09c5b62810b14ecd81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 38975,
"upload_time": "2024-05-09T16:27:42",
"upload_time_iso_8601": "2024-05-09T16:27:42.672655Z",
"url": "https://files.pythonhosted.org/packages/91/8d/1de01a01a254f13cf7d4a9963c20ce5ec7c269768f52bf7286ecf9d5d9c3/domaintools_api_v2-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-09 16:27:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "domaintools",
"github_project": "python_api",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "domaintools-api-v2"
}
