Package: ipdata
Official Python client library and CLI for the ipdata APIThis is a Python client and command line interface (CLI) for theipdata.coIP 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 bySigning up here.Visit ourDocumentationfor more examples and tutorials.InstallationInstall the latest version of the cli withpip.pipinstallipdataoreasy_installeasy_installipdataLibrary UsageYou need a valid API key from ipdata to use the library. You can get a free key bySigning up here.Replacetestwith your API Key in the following examples.Looking up the calling IP AddressYou 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 thelookupmethod.>>>importipdata>>>ipdata.api_key="<YOUR API KEY>">>>ipdata.lookup()Looking up any IP AddressYou can look up any valid IPv4 or IPv6 address by passing it to thelookupmethod.>>>importipdata>>>ipdata.api_key="<YOUR API KEY>">>>response=ipdata.lookup('69.78.70.144')pprint(response)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 fieldIf you only need a single data attribute about an IP address you can extract it by passing aselect_fieldparameter to thelookupmethod.>>>importipdata>>>ipdata.api_key="<YOUR API KEY>">>>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 fieldsIf instead you need to get multiple specific fields you can pass a list of valid field names in afieldsparameter.>>>importipdata>>>ipdata.api_key="<YOUR API KEY>">>>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 LookupsThe API provides a/bulkendpoint 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 theipdatacli'sbatchcommand. 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 theCLI Bulk Lookup Documentationfor details.>>>importipdata>>>ipdata.api_key="<YOUR API KEY>">>>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
}Using the ipdata CLIWindows Installation NotesIPData CLI needsPython 3.9+. Python Windows installation program
provides PIP so you can install IPData CLI the same way:pip install ipdataAvailable commandsipdata--help
Usage:ipdata[OPTIONS]COMMAND[ARGS]...WelcometotheipdataCLI

Options:--api-keyTEXTYouripdataAPIKey.Getoneforfreefromhttps://ipdata.co/sign-up.html--helpShowthismessageandexit.

Commands:lookup*LookupresourcesbyusingtheIPDataclassmethods.batchBatchcommandfordoingfastbulkprocessing.initInitializetheCLIbysettinganAPIkey.usageGettoday'susage.validateValidatesageofeedfile.Initialize the cli with your API KeyYou need a valid API key from ipdata to use the cli. You can get a free key bySigning up here.ipdatainit<APIKey>___(_)_____||___||____||'_\/_`|/_`|__/_`||||_)|(_||(_||||(_|||_|.__/\__,_|\__,_|\__\__,_||_|✨Successfullyinitialized.You can also pass the--api-key <API Key>parameter to any command to specify a different API Key.Look up your own IP addressRunning theipdatacommand without any parameters will look up the IP address of the computer you are running the command on. Alternatively you can explicitly look up your own IP address by runningipdata.ipdataTo pretty print the result pass the-pflag╭────────────────────────────────╮ ╭────────────╮ ╭─────────────────╮ ╭──────────╮ ╭─────────────╮ ╭───────────────╮ ╭──────────────╮ ╭────────────────╮ ╭────────────────╮ ╭────────╮ ╭──────────────╮
│ ip                             │ │ is_eu      │ │ city            │ │ region   │ │ region_code │ │ country_name  │ │ country_code │ │ continent_name │ │ continent_code │ │ postal │ │ calling_code │
│ 24.24.24.24                    │ │ False      │ │ Syracuse        │ │ New York │ │ NY          │ │ United States │ │ US           │ │ North America  │ │ NA             │ │ 13261  │ │ 1            │
╰────────────────────────────────╯ ╰────────────╯ ╰─────────────────╯ ╰──────────╯ ╰─────────────╯ ╰───────────────╯ ╰──────────────╯ ╰────────────────╯ ╰────────────────╯ ╰────────╯ ╰──────────────╯
╭────────────────────────────────╮ ╭────────────╮ ╭─────────────────╮ ╭──────────╮                                                                                                                     
│ flag                           │ │ emoji_flag │ │ emoji_unicode   │ │ count    │                                                                                                                     
│ https://ipdata.co/flags/us.png │ │ 🇺🇸         │ │ U+1F1FA U+1F1F8 │ │ 4086     │                                                                                                                     
╰────────────────────────────────╯ ╰────────────╯ ╰─────────────────╯ ╰──────────╯                                                                                                                     
╭────────────────────────────────╮ ╭──────────────────╮ ╭─────────────────╮ ╭────────────────╮ ╭───────────────────────────────╮ ╭───────────────────────╮
│ asn                            │ │ company          │ │ languages       │ │ currency       │ │ time_zone                     │ │ threat                │
│ ├── asn                        │ │ ├── name         │ │ └──             │ │ ├── name       │ │ ├── name                      │ │ ├── is_tor            │
│ │   AS11351                    │ │ │   Rr-Route     │ │     ├── name    │ │ │   US Dollar  │ │ │   America/New_York          │ │ │   False             │
│ ├── name                       │ │ ├── domain       │ │     │   English │ │ ├── code       │ │ ├── abbr                      │ │ ├── is_icloud_relay   │
│ │   Charter Communications Inc │ │ │                │ │     ├── native  │ │ │   USD        │ │ │   EDT                       │ │ │   False             │
│ ├── domain                     │ │ ├── network      │ │     │   English │ │ ├── symbol     │ │ ├── offset                    │ │ ├── is_proxy          │
│ │   spectrum.com               │ │ │   24.24.0.0/19 │ │     └── code    │ │ │   $          │ │ │   -0400                     │ │ │   False             │
│ ├── route                      │ │ └── type         │ │         en      │ │ ├── native     │ │ ├── is_dst                    │ │ ├── is_datacenter     │
│ │   24.24.0.0/18               │ │     business     │ ╰─────────────────╯ │ │   $          │ │ │   True                      │ │ │   False             │
│ └── type                       │ ╰──────────────────╯                     │ └── plural     │ │ └── current_time              │ │ ├── is_anonymous      │
│     business                   │                                          │     US dollars │ │     2022-07-15T16:59:44-04:00 │ │ │   False             │
╰────────────────────────────────╯                                          ╰────────────────╯ ╰───────────────────────────────╯ │ ├── is_known_attacker │
                                                                                                                                 │ │   False             │
                                                                                                                                 │ ├── is_known_abuser   │
                                                                                                                                 │ │   False             │
                                                                                                                                 │ ├── is_threat         │
                                                                                                                                 │ │   False             │
                                                                                                                                 │ ├── is_bogon          │
                                                                                                                                 │ │   False             │
                                                                                                                                 │ └── blocklists        │
                                                                                                                                 │     []                │
                                                                                                                                 ╰───────────────────────╯Look up any IP addressYou can pass any valid IPv4 or IPv6 address to theipdatacommand to look it up. In case an invalid value is passed you will get the errorERROR    'BLEH' does not appear to be an IPv4 or IPv6 address".ipdata8.8.8.8Copying results to clipboardUse-cto copy the results to the clipboard!ipdata 1.1.1.1 -f ip -f asn -c 
📋️ Copied result to clipboard!Filtering results by a list of fieldsUse--fieldsto filter the responsesipdata--fieldscity--fieldscountry_name'or use-fipdata1.1.1.1-fip-fasn{"ip":"1.1.1.1","asn":{"asn":"AS13335","name":"Cloudflare, Inc.","domain":"cloudflare.com","route":"1.1.1.0/24","type":"business"},"status":200}Batch lookupPerhaps the most useful command provided by the CLI is the ability to process a csv file with a list of IP addresses and write the results to file as either CSV or JSONL/NDJSON! It could be a list of tens of thousands to millions of IP addresses and it will all be processed and the results filtered to your liking!When you use the JSON output format, the results are written to the output file you provide with one result per line. Each line being a valid and full JSON response object.
If you only need a few fields eg. only the country name you can specify a field argument with the names of the fields you want, if you combine this with the CSV output format you will get very clean results with only the data you need!To get full JSON responses for further processingThis is the default output format, so you could omit the--format JSONipdata batch my_ip_backlog.csv --output geolocation_results.json --format JSONBatch lookup with output to CSV fileipdata batch my_ip_backlog.csv --output results.csv --output-format CSV --fields ip --fields country_codeThe--fieldsoption is required to use CSV output.Example Results# ip,country_code
107.175.75.83,US
35.155.95.229,US
13.0.0.164,US
209.248.120.14,US
142.0.202.238,US
...Available FieldsA list of all the fields returned by the API is maintained atResponse FieldsGeofeed toolsGeofeed publishers can use theipdata validatecommand to validate their geofeeds before submission to ipdata. This will catch most but not all issues that might cause processing your geofeed to fail.The validation closely followshttps://datatracker.ietf.org/doc/html/draft-google-self-published-geofeeds-02with one caveat, we expect the country field to be provided at the minimum.You can provide either a url or a path to a local file.ipdatavalidatehttps://example.com/geofeed.txtoripdatavalidategeofeed.txtErrorsA list of possible errors is available atStatus CodesTestsTo run all testspytest