Official Python client library and CLI for the ipdata API

This is a Python client and command line interface (CLI) for the ipdata.co IP Geolocation API. ipdata offers a fast, highly-available API to enrich IP Addresses with Location, Company, Threat Intelligence and numerous other data attributes.

Note that you need an API Key to use this package. You can get a free one with a 1,500 daily request limit by Signing up here.

Visit our Documentation for more examples and tutorials.

Installation

Install the latest version of the cli with pip.

pip install ipdata

or easy_install

easy_install ipdata

Library Usage

You need a valid API key from ipdata to use the library. You can get a free key by Signing up here.

Replace test with your API Key in the following examples.

Looking up the calling IP Address

You can look up the calling IP address, that is, the IP address of the computer you are running this on by not passing an IP address to the lookup method.

>>> import ipdata
>>> ipdata.api_key = "<<apiKey>>"
>>> data = ipdata.lookup()
>>> data.country_name
"United States"

Looking up any IP Address

You can look up any valid IPv4 or IPv6 address by passing it to the lookup method.

>>> import ipdata
>>> ipdata.api_key = "<<apiKey>>"
>>> data = ipdata.lookup('69.78.70.144')
>>> data.country_name

Sample Response

{
  "ip": "69.78.70.144",
  "is_eu": false,
  "city": null,
  "region": null,
  "region_code": null,
  "country_name": "United States",
  "country_code": "US",
  "continent_name": "North America",
  "continent_code": "NA",
  "latitude": 37.750999450683594,
  "longitude": -97.8219985961914,
  "postal": null,
  "calling_code": "1",
  "flag": "https://ipdata.co/flags/us.png",
  "emoji_flag": "\ud83c\uddfa\ud83c\uddf8",
  "emoji_unicode": "U+1F1FA U+1F1F8",
  "asn": {
    "asn": "AS6167",
    "name": "Verizon Business",
    "domain": "verizon.com",
    "route": "69.78.0.0/17",
    "type": "business"
  },
  "company": {
    "name": "Verizon Business",
    "domain": "verizon.com",
    "network": "69.78.0.0/17",
    "type": "business"
  },
  "carrier": {
    "name": "Verizon",
    "mcc": "310",
    "mnc": "004"
  },
  "languages": [
    {
      "name": "English",
      "native": "English",
      "code": "en"
    }
  ],
  "currency": {
    "name": "US Dollar",
    "code": "USD",
    "symbol": "$",
    "native": "$",
    "plural": "US dollars"
  },
  "time_zone": {
    "name": null,
    "abbr": null,
    "offset": null,
    "is_dst": null,
    "current_time": null
  },
  "threat": {
    "is_tor": false,
    "is_icloud_relay": false,
    "is_proxy": false,
    "is_datacenter": false,
    "is_anonymous": false,
    "is_known_attacker": false,
    "is_known_abuser": false,
    "is_threat": false,
    "is_bogon": false,
    "blocklists": []
  },
  "count": "3895",
  "status": 200
}

Getting only one field

If you only need a single data attribute about an IP address you can extract it by passing a select_field parameter to the lookup method.

>>> import ipdata
>>> ipdata.api_key = "<<apiKey>>"
>>> ipdata.lookup('8.8.8.8', select_field='asn')

Response

{
  "asn": {
    "asn": "AS15169",
    "name": "Google LLC",
    "domain": "about.google",
    "route": "8.8.8.0/24",
    "type": "business"
  },
  "status": 200
}

Getting a number of specific fields

If instead you need to get multiple specific fields you can pass a list of valid field names in a fields parameter.

>>> import ipdata
>>> ipdata.api_key = "<<apiKey>>"
>>> ipdata.lookup('8.8.8.8',fields=['ip','asn','country_name'])

Response

{
  "ip": "8.8.8.8",
  "asn": {
    "asn": "AS15169",
    "name": "Google LLC",
    "domain": "about.google",
    "route": "8.8.8.0/24",
    "type": "business"
  },
  "country_name": "United States",
  "status": 200
}

Bulk Lookups

The API provides a /bulk endpoint that allows you to look up upto 100 IP addresses at a time. This is convenient for quickly clearing your backlog.

NOTE: Alternatively it is much simpler to process bulk lookups using the ipdata cli's batch command. All you need is a csv file with a list of IP addresses and you can get your results as either a JSON file or a CSV file! See the CLI Bulk Lookup Documentation for details.

>>> import ipdata
>>> ipdata.api_key = "<<apiKey>>"
>>> ipdata.bulk(['8.8.8.8','1.1.1.1'])

Sample Response

{
  "responses": [
    {
      "ip": "8.8.8.8",
      "is_eu": false,
      "city": null,
      "region": null,
      "region_code": null,
      "country_name": "United States",
      "country_code": "US",
      "continent_name": "North America",
      "continent_code": "NA",
      "latitude": 37.750999450683594,
      "longitude": -97.8219985961914,
      "postal": null,
      "calling_code": "1",
      "flag": "https://ipdata.co/flags/us.png",
      "emoji_flag": "\ud83c\uddfa\ud83c\uddf8",
      "emoji_unicode": "U+1F1FA U+1F1F8",
      "asn": {
        "asn": "AS15169",
        "name": "Google LLC",
        "domain": "about.google",
        "route": "8.8.8.0/24",
        "type": "business"
      },
      "company": {
        "name": "Google LLC",
        "domain": "google.com",
        "network": "8.8.8.0/24",
        "type": "business"
      },
      "languages": [
        {
          "name": "English",
          "native": "English",
          "code": "en"
        }
      ],
      "currency": {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "native": "$",
        "plural": "US dollars"
      },
      "time_zone": {
        "name": null,
        "abbr": null,
        "offset": null,
        "is_dst": null,
        "current_time": null
      },
      "threat": {
        "is_tor": false,
        "is_icloud_relay": false,
        "is_proxy": false,
        "is_datacenter": false,
        "is_anonymous": false,
        "is_known_attacker": false,
        "is_known_abuser": false,
        "is_threat": false,
        "is_bogon": false,
        "blocklists": []
      },
      "count": "3931"
    },
    {
      "ip": "1.1.1.1",
      "is_eu": null,
      "city": null,
      "region": null,
      "region_code": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal": null,
      "calling_code": null,
      "flag": null,
      "emoji_flag": null,
      "emoji_unicode": null,
      "asn": {
        "asn": "AS13335",
        "name": "Cloudflare, Inc.",
        "domain": "cloudflare.com",
        "route": "1.1.1.0/24",
        "type": "business"
      },
      "company": {
        "name": "Cloudflare, Inc.",
        "domain": "cloudflare.com",
        "network": "1.1.1.0/24",
        "type": "business"
      },
      "languages": null,
      "currency": {
        "name": null,
        "code": null,
        "symbol": null,
        "native": null,
        "plural": null
      },
      "time_zone": {
        "name": null,
        "abbr": null,
        "offset": null,
        "is_dst": null,
        "current_time": null
      },
      "threat": {
        "is_tor": false,
        "is_icloud_relay": false,
        "is_proxy": false,
        "is_datacenter": false,
        "is_anonymous": false,
        "is_known_attacker": false,
        "is_known_abuser": false,
        "is_threat": false,
        "is_bogon": false,
        "blocklists": []
      },
      "count": "3931"
    }
  ],
  "status": 200
}

Errors

A list of possible errors is available at Status Codes

Tests

To run all tests

pytest