Automating Tasks with the SpatialScale REST API

Ready to automate your geospatial workflows? The SpatialScale REST API is your ticket to discovering, storing, and analyzing geospatial data at cloud scale. This guide will walk you through the basics, making it easy to integrate into your applications.

Step 1: Authentication

First things first, you need to authenticate. The SpatialScale API uses OAuth 2.0, and you'll need an access token to get started.

Here’s how you generate a token:

Navigate to Access Tokens: Log in to your SpatialScale account and go to the Access Tokens page.
Click ‘+ Create’: Hit that ‘Create’ button.
Name Your Token: Call it “API Example” or something you’ll remember.
Enable Scopes: Ensure assets:read, assets:write, and assets:list are enabled.
Create and Copy: Click ‘Create’ and then copy your new token to the clipboard.

With your token in hand, you’re ready to start automating!

Step 2: List Datasets with cURL

Let’s test your new token by listing the datasets in your account. Use this cURL command:

curl "https://api.spatialscale.com/v1/datasets" -H "Authorization: Bearer <access_token>"

IReplace <access_token> with the token you just created. If everything’s working, you’ll see a JSON output like {'data': [], 'count': 0}. That means your request was successful!

Step 3: Understanding Scopes

Scopes in SpatialScale help control what your access token can do. Here are the main ones:

assets:read: Access and read metadata for your assets.
assets:list: List all available assets.
assets:write: Modify or delete assets (keep this scope secret!).

Understanding these scopes helps you manage your API’s capabilities securely.

Step 4: Using Python for API Requests

Now, let’s simplify your requests by using Python. The requests library makes API calls a breeze.

Here’s how to list datasets in Python:

import requests

ACCESS_TOKEN = "<access_token>"

def get_datasets():
    return requests.get(
        url="https://api.spatialscale.com/v1/datasets",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
    ).json()

if __name__ == "__main__":
    results = get_datasets()

Just replace <access_token> with your actual token, and you’re good to go!

Step 5: Extracting Geospatial Data

Want to extract some imagery? Let’s get data covering the UT Austin area:

import requests

ACCESS_TOKEN = "<access_token>"

def find_data(payload):
    return requests.post(
        url="https://api.spatialscale.com/v1/discover/search",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
        json=payload,
    ).json()

def extract_data(payload):
    return requests.post(
        url="https://api.spatialscale.com/v1/discover/extract",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
        json=payload,
    ).json()

if __name__ == "__main__":
    aoi = {
        "type": "Feature",
        "properties": {},
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [-97.74398803710938, 30.273226302036015],
                    [-97.71785259246826, 30.273226302036015],
                    [-97.71785259246826, 30.295758037778036],
                    [-97.74398803710938, 30.295758037778036],
                    [-97.74398803710938, 30.273226302036015],
                ]
            ],
        },
    }

    search_payload = {
        "collection_type": "raster",
        "collection_id": "naip",
        "collection_name": "NAIP: National Agriculture Imagery Program",
        "collection_product_type": "natural_color",
        "aoi": aoi,
    }

    config = find_data(search_payload)
    config["dataset_name"] = "UT Austin - NAIP"
    config["crop_to_aoi"] = True
    results = extract_data(config)

After running this, check your Datasets page—you’ll see a new dataset created!

Need More Help?

Explore more about the SpatialScale REST API on our API Documentation. If you get stuck, our Help Center is just a click away.

Happy automating!