Get started with the Splashback REST 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.

venv

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!

Conda

1. Create a Conda build folder

Firstly, create a folder for performing a Conda build of the client package. Give the folder a descriptive name. I'll refer to this as the 'build folder' for the rest of these instructions.

2. Create a Conda build recipe

Next, we need to create the Conda build recipe which tells Conda how to handle our new package. Create a file called meta.yaml in the build folder with the following content. Be sure to replace <path_to_generated_splashback_data_package> with the path to your generated package.

package:  name: splashback_data  version: 1.0.0
source:  path: <path_to_generated_splashback_data_package>
build:  noarch: python  number: 0  script: {{PYTHON}} -m pip install . -vv
requirements:  build:    - python    - pip  run:    - python    - python-dateutil >=2.5.3    - urllib3 >=1.25.3

3. Build the Conda package

Before building the package, ensure that you have the correct Conda environment activated. You can usually tell by the prefix at the start of your shell prompt.

From the build folder, run the following commands:

(base) $ conda build . -c defaults -c conda-forge

tip

If you see the error:

CommandNotFoundError: To use 'conda build', install conda-build.

Run:

(base) $ conda install conda-build

4. Install the package

(base) $ conda install --use-local splashback_data(base) $ conda install -c conda-forge python-dateutil

5. Test the installed package

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

(base) $ 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

venv

In your venv, run the following command:

(venv) $ pip install python-dotenv

Conda

In your Conda environment, run the following command:

(base) $ conda install -c conda-forge python-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

venv

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>>>>

Conda

In your Conda environment, run the following command:

(base) $ 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 osimport timeimport splashback_datafrom dotenv import load_dotenvfrom pprint import pprintfrom splashback_data.api import sites_api
# Load .envload_dotenv()
# Setup the API configurationconfiguration = splashback_data.Configuration(    host = "https://api.splashback.io/data")
# Configure API key authorization: api-keyconfiguration.api_key['api-key'] = os.environ.get('SPLASHBACK_API_KEY')configuration.api_key_prefix['api-key'] = 'API-Key'
# Set your Pool IDpool_id = <your_pool_id_here>
# Enter a context with an instance of the API clientwith 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)

venv

In your venv, run the following command:

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

Conda

In your Conda environment, run the following command:

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

You should see your sites listed out on the screen!