Get started with the Splashback API in Python

Splashback can be used in Python by making calls to our APIs. We have many endpoints available, covering everything from data querying to user management.

Accessing the Splashback APIs from Python is easy, however getting meaningful use out of them can be challenging. You will need a good understanding of our data structure. We recommend reading through the core concepts, and specifically the information on Sample data.

To get started, make sure you have a working installation of Python 3.

Generate the client#

Follow the instructions in the example to generate a Python package for the Data service, ensuring sure you use the -g python option. We will assume its --package-name is splashback_data for this tutorial, but feel free to use another if this doesn't suit your needs.

Install the client#

Depending on your use case, there are a few ways to install the generated package.

We recommend using a virtual environment (venv) for developing with Splashback API as it is easy to setup and maintain, and is standalone from your global Python installation.

1. Create a new venv

You can skip this step if you have an existing venv.

To create a new venv in a new project folder, splashback_data_demo:

$ mkdir splashback_data_demo
$ cd splashback_data_demo
$ python3 -m venv venv

2. Activate the venv and install the packages

Next, install the package to the venv:

$ source venv/bin/activate
(venv) $ pip install wheel
(venv) $ pip install <path_to_generated_splashback_data_package>

3. Test the installed package

Now, to check if you have the package installed, run the following in the venv:

(venv) $ python
>>> import splashback_data
>>> print(splashback_data)
<module 'splashback_data' from '...'>
>>>

If you see the <module 'splashback_data' from '...'> output, you're all set!

Set your API key#

To authenticate requests with Splashback, we use an API key. Read more about API keys and best security practices and generate an API key before continuing.

Environment variables are a common way to keep API keys out of source code. We will show you how to use the Python dotenv package to load the API key from a file, but there are other ways to do this depending on your use case.

1. Install dotenv

In your venv, run the following command:

(venv) $ pip install dotenv

2. Create a .env file

Next, we will need to create a .env file in the root of our project, with the following content:

SPLASHBACK_API_KEY='<your_api_key_here>'
warning

Make sure to exclude this file from any version control system (VCS) such as Git, SVN or Mercurial and never share it with other people!

3. Check the API key can be read

In your venv, run the following command:

(venv) $ python
>>> from dotenv import load_dotenv
>>> load_dotenv()
>>> import os
>>> print(os.environ.get('SPLASHBACK_API_KEY'))
<your_api_key_here>
>>>

If you see your API key in the output, you're all set!

Make your first query#

Wow, we made it to the fun part! Let's bring everything we've learnt together into one script which will get all the sites in a Pool!

Make sure you replace your Pool ID in the code below, and save it to a file main.py in your project root:

import os
import time
import splashback_data
from dotenv import load_dotenv
from pprint import pprint
from splashback_data.api import sites_api
# Load .env
load_dotenv()
# Setup the API configuration
configuration = splashback_data.Configuration(
host = "https://api.splashback.io/data"
)
# Configure API key authorization: api-key
configuration.api_key['api-key'] = os.environ.get('SPLASHBACK_API_KEY')
configuration.api_key_prefix['api-key'] = 'API-Key'
# Set your Pool ID
pool_id = <your_pool_id_here>
# Enter a context with an instance of the API client
with splashback_data.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = sites_api.SitesApi(api_client)
try:
# List of fields that can be passed to the Export endpoint.
api_response = api_instance.api_sites_pool_id_get(pool_id=pool_id)
pprint(api_response)
except splashback_data.ApiException as e:
print("Exception when calling SitesApi->api_sites_pool_id_get: %s\n" % e)

In your venv, run the following command:

(venv) $ python main.py
[{...},
{...}]

You should see your sites listed out on the screen!