This is the documentation for the Python client for Objectia® API. You can find the source code for the client on GitHub. We have API clients in several other programming languages hosted on GitHub.


The Python client for Objectia API requires Python version 3.4 or later. If you’re using a Mac or Linux machine, you probably already have Python installed. You can check this by opening up a terminal and running the following command:

python --version

You should see something like:

Python 3.7.1

Windows users can follow this tutorial for installing Python on Windows, or follow the instructions from Python's documentation.


The easiest way to install the library is using pip, a package manager for Python that makes it easier to install the libraries you need. Simply run this in the terminal:

pip install objectia

If you get a pip: command not found error, you can also use easy_install by running this in your terminal:

easy_install objectia

If you'd prefer a manual installation, you can download the source code (ZIP) for objectia-python and then install the library by running:

python install

in the folder containing the objectia-python library.


Now that we have Python and objectia-python installed, we can start using the API. In the example below we will look up the geolocation of the IP address

import os
import objectia

APIKEY = os.environ.get("OBJECTIA_APIKEY")

client = objectia.Client(api_key=APIKEY)
location = client.geoip.get("")
print("Country code: {0}".format(location["country_code"]))


If you do not have an API Key, you can easily generate one by heading over to the API settings page.

Error handling

Handle errors with try...except:

import objectia
from objectia.errors import ResponseError

# If you enter an invalid IP address, we get an error
    client = objectia.Client(api_key="YOUR-API-KEY")
    location = client.geoip.get("x")
except ValueError as e:
    # Missing API key?
except ResponseError as e:
	if e.code == "err-invalid-ip":
		# Handle error...
		# Other error...

You will find all the error codes in the REST API documentation.