sraking/metaip repository overview

⁠metaip

A small command line utility that utilizes the API of ipstack to return the latitude and longitude associated with an IP address in JSON notation.

⁠🚀 Quick Start

⁠📋 Prerequisites

• Python >= 3.8.
• Get an API key from ipstack.com⁠

The following are optional but are recommended

• A pipx installation.

⁠💾 Installation

metaip can be installed into any python environment using pip:

~ $ pip install metaip

However, optimal installation can be achieved using pipx⁠:

~ $ pipx install metaip

For a development installation:

Editable (developer) installs were not possible prior to 2021, but that has been remedied by pep 660⁠. This can be performed by either 'pip' or 'setuptools'. Clone or fork the repository first then:

$ python -m pip install -e .

or

$ python setup.py develop

⁠📝 Basic Usage

Issue the command to get meta data about IP address specifying the API key

$ metaip 90.203.98.132 -k <api_key>

the result is return as JSON

{
    "ip": "90.203.98.132",
    "coordinates": {
        "latitude": 53.78388977050781,
        "longitude": -1.787500023841858
    }
}

Note: the API key is now stored for future use. More on this later.

⁠📝 Usage

On first usage, if an API key is not specified from the command line, you will be asked to supply one:

$ metaip 90.203.98.132
Please enter your API key:

once the API key has benn entered, the coordinate information is returned as JSON

Please enter your API key:<api-key>
{
    "ip": "90.203.98.132",
    "coordinates": {
        "latitude": 53.78388977050781,
        "longitude": -1.787500023841858
    }
}

Once the key has been entered once it is stored so you will not be asked for it again.

$ metaip 90.203.98.132
{
    "ip": "90.203.98.132",
    "coordinates": {
        "latitude": 53.78388977050781,
        "longitude": -1.787500023841858
    }
}

You can store a new key at any time by using the '-k' argument from the command line:

$>metaip 90.203.98.132 -k <api_key>
{
    "ip": "90.203.98.132",
    "coordinates": {
        "latitude": 53.78388977050781,
        "longitude": -1.787500023841858
    }
}

This new key will then be stored for future use.

⁠🔒 Security Considerations

Obviously when dealing with API keys, the key should never be hard coded in the application. There are a multitude of ways to deal with API keys (including using environment variables etc). To avoid hard-coding any credentials I use the Python keyring⁠ library

Note: On Linux, the KWallet backend relies on dbus-python, which does not always install correctly when using pip (compilation is needed). For best results, install dbus-python as a system package. If keyring is not working then the fallback is to use the '-k' argument.

⁠🧬 Design

As ipstack.com⁠ is a paid for service I have used the Look Before You Leap (LBYL) design principle to check Ip addresses and API keys. This approach involves checking for preconditions or potential issues before taking an action. This is generally seen as unpythonic. However to issue malformed requests would be wasteful on resources. Generally speaking the Easier to Ask for Forgiveness than Permission (EAFP) is more pythonic which involves trying an action first and then handling any exceptions or errors if they occur.

⁠🐳 Using Docker

⁠Building the Image

Start your docker runtime then:

docker build -t {{ repository }}/metaip:{{version}} . e.g.

$ docker build -t sraking/metaip:0.1.0 -t sraking/metaip:latest .

Run the image (creates the container) - docker run -it {{ repository }}/metaip:{{version}} /bin/bash e.g.

$ docker run -it sraking/metaip:0.1.0 /bin/bash

Upload the image to docker hub - docker push {{ repository }}/metaip:{{version}} e.g.

$ docker push sraking/metaip:0.1.0

⁠Using the ready built image

Pull the latest image from the Hub.

~ $ docker pull sraking/metaip

Run the image.

~ $ docker run -it sraking/metaip /bin/bash

Use the command line as normal in the container.

root@4d315992ca28:/app# metaip -k <api_key>
{
    "ip": "90.203.98.132",
    "coordinates": {
        "latitude": 53.78388977050781,
        "longitude": -1.787500023841858
    }
}

⁠⚠️ Limitations

The IP addresses are restricted to IPv4 addresses.

⁠📜 License

Distributed under the MIT license. See for more information.