Skip to main content

FarEarth API configuration

This document provides an overview of how to get started using FarEarth's APIs.

Testing API key​

You can use the following curl example to verify that the API key works:

curl -H "Content-Type: application/json" \
  -H "X-API-Key: <insert API key>" \
  -X GET https://gateway.farearth.space/api/ext/v1/test/hello

OpenAPI schemas​

To assist with creating your own API integration, an OpenAPI JSON schema file is available at https://gateway.farearth.space/api/public/api-schema/subscription.

STAC access​

Below is an example using PySTAC to query the FarEarth Catalogue APIs. The example uses an environment variable, namely FE3_API_KEY, that contains the API key (see steps to obtain a unique user API key at the top of this page)

import os
import urllib

FE3_API_URL=R"https://gateway.farearth.space/api/ext/v1/stac/catalogs/farearth.gateway-bundled/farearth.gateway-bundled"

if __name__ == "__main__":

    catalog = Client.open(
        url=FE3_API_URL,
        headers={
            'X-API-Key': os.environ['FE3_API_KEY']
        }
    )

    # Get all the collections that the API key has access to
    collections = catalog.get_collections()

    for collection in collections:
        print(collection)
        # Use the last specified collection
        specific_collection_name = collection.id

    # Get an object representing a specific collection
    specific_collection = catalog.get_collection(specific_collection_name)

    search = catalog.search(
        max_items=30,
        limit=3,
        collections=[specific_collection],
        bbox=[8.518128, 3.663501, 42.038028, -35.811674],
    )

    print(f"{search.matched()} items found")

    for item in search.items():

        # Download thumbnails (previews) if they are available
        if 'THUMB_RGB' in item.assets:
            urllib.request.urlretrieve(item.assets["THUMB_RGB"].href, f"{item.id}_PREVIEW.png")

        # Alternatively, you can download an asset based on its role
        for key, value in item.assets.items():
            if value.roles == 'metadata':
                urllib.request.urlretrieve(item.assets[key].href, f"{item.id}_META.json")

More examples​

For more examples on how to interact with the APIs, see examples.