Quickstart

This guide describes how to start using Specklia using Specklia’s Python client.

To start using Specklia, you must first obtain an API key. This can be done using a number of pre-existing accounts such as with your Google or Github account. Please use the same kind of account each time you wish to generate or re-generate an API key for Specklia. We recommend saving your API key to a file. The remainder of this guide will assume that you have saved it into a file called “my_api_key.txt” in your python working directory.

Once you have an API key, install the Specklia python client using PyPI:

pip install specklia

Next, create a client, passing in your API key as an argument:

from specklia import Specklia

with open("my_api_key.txt") as file_stream:
    client = Specklia(file_stream.read())

You can list the datasets that you have access to using:

client.list_datasets()

Note that this function returns a pandas DataFrame describing the space-time extent of the dataset and the fields available for each point. Let’s say that one of the datasets you have listed has the dataset_id 12345678-9abc-defg-hijk-lmnopqrstuvw and has the non-default fields elevation and uncertainty. You want to obtain all of the values of the elevation field for points where uncertainty is less than 5, over Barents Island, Svalbard, from 1st April 2015 to 1st September 2016. You would run this query like so:

from datetime import datetime
from shapely import Polygon

barents_island_polygon = Polygon((
    (21.965, 78.717),
    (19.928, 78.528),
    (20.557, 78.122),
    (22.751, 78.309),
    (21.965, 78.717)
))

result = client.query_dataset(
    dataset_id='12345678-9abc-defg-hijk-lmnopqrstuvw',
    epsg4326_polygon=barents_island_polygon,
    min_datetime=datetime(2015, 3, 1),
    max_datetime=datetime(2015, 9, 1),
    columns_to_return=['elevation'],
    additional_filters=[{'column': 'uncertainty', 'operator': '<=', 'threshold': 5}]
)

The result is a GeoDataFrame which can be readily manipulated further. Note that queries generally take tens of seconds, but can take longer for particularly large queries. Excessively large queries are likely to time out before completion. If you are persistently unable to run a query that you believe you should be able to run, please contact support@earthwave.co.uk.