Skip to main content

A small cache layer for IP geolocation info

Project description


PyPi version Python 3.6|3.7|3.8 PRs Welcome

A small cache layer for IP geolocation info.

import ipgeocache
ipgeocache.get("<some ip address>")

If that IP has been requested before, it returns the information from cache. Else, it requests out to


Requires python3.6+

To install with pip, run:

pip install ipgeocache

This requires you to get an access token from here, can do 50,000 lookups per month as long as you're using it for non-commercial projects.

After setting the IPINFO_TOKEN environment variable:

>>> import ipgeocache, logzero
>>> ipgeocache.get("", logger=logzero.logger)["hostname"]
[D 200906 17:56:31 __init__:62] Cache Miss:, requesting and writing to /home/sean/.local/share/ipgeocache/

>>> ipgeocache.get("", logger=logzero.logger)["hostname"]
[D 200906 17:56:35 __init__:58] Cache Hit:, reading /home/sean/.local/share/ipgeocache/

>>> ipgeocache.get("")
{'ip': '',
 'hostname': '',
 'city': 'Mountain View',
 'region': 'California',
 'country': 'US',
 'loc': '37.4056,-122.0775',
 'org': 'AS15169 Google LLC',
 'postal': '94043',
 'timezone': 'America/Los_Angeles'}

Purpose is to just be a thin wrapper that caches this info, so I don't have to think about it for my random projects.

The full function signature is:

ipgeocache.get(ip_address: str,
              token: Optional[str] = None,
              cache_dir: Optional[str] = None,
              logger: Optional[logging.Logger] = None) -> Dict[str, Any]

    Get geolocation info for an IP address

    optional parameters:
    token: ipinfo token to use, if IPINFO_TOKEN not set as an environment variable
    cache_dir: directory to use for cache, overrides default (XDG_DATA_DIR/ipgeocache) if given
    logger: a logger to send cache hit/miss info out on

To change where this stores IP info, you can set the IPGEOCACHE_DIR environment variable.


Also installs a basic ipgeocache script, which you can pass an IP address to:

$ ipgeocache --help
Usage: ipgeocache [OPTIONS] IP

  Gets geolocation information for an IP address

  For example: 'ipgeocache'

  --ipinfo-token TEXT  Authentication token to use ipinfo API.

  --json               Print geolocation info as JSON
  --help               Show this message and exit.
$ ipgeocache --json
    "city": "Mountain View",
    "country": "US",
    "hostname": "",
    "ip": "",
    "loc": "37.4056,-122.0775",
    "org": "AS15169 Google LLC",
    "postal": "94043",
    "region": "California",
    "timezone": "America/Los_Angeles"

Also accessible like python -m ipgeocache

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

ipgeocache-0.1.4.tar.gz (5.6 kB view hashes)

Uploaded source

Built Distribution

ipgeocache-0.1.4-py3-none-any.whl (6.3 kB view hashes)

Uploaded py3

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