Skip to main content

Create a Gridded Dataset

tip

OlmoEarth API Endpoints

OlmoEarth API endpoints are documented in the Interactive OlmoEarth API Browser.

You can use it to understand request and response schemas, make requests directly to the API, and generate client code in many common languages and libraries.

The following OlmoEarth API endpoints are used in this guide:

This guide explains how to create a gridded dataset using the OlmoEarth API. A gridded dataset divides a geographic area into a grid of smaller windows, each containing satellite imagery from your specified data sources.

Prerequisites​

API Token​

To get your API Token, see Authentication

Project ID​

Datasets must be uploaded to a Project. To get a Project ID, view Your Projects, select your project, and copy the ID from the URL.

For example, if your project URL is:

https://olmoearth.allenai.org/projects/7e160260-5a5a-4120-ab33-8ce15998b982/tasks

Then your Project ID is 7e160260-5a5a-4120-ab33-8ce15998b982

Components of the request​

1. Geometry​

An Area of Interest has both a geometry and a time range. OlmoEarth will attempt to acquire data that covers the geometry within the time range specified. To create the gridded dataset, the geometry of your Area must be in WKT format. For this guide, we will use this WKT geometry that defines an area in Seattle, Washington:

POLYGON((-122.365581 47.62529, -122.365581 47.655588, -122.319025 47.655588, -122.319025 47.62529, -122.365581 47.62529))

2. Sources and Time Ranges​

Here we define the time ranges for the Area of Interest. Each source time range must define:

  1. The data source for imagery
  2. The time range to look for imagery, specified by start_time and end_time
  3. The number of images to acquire, specified by count

Valid Options for the source include:

  • sentinel1_vv_vh - Sentinel-1 Low resolution radar imagery
  • sentinel2_tci - Sentinel-2 High-resolution optical imagery
  • landsat - Landsat Multispectral imagery
  • naip - NAIP High-resolution aerial imagery of the US
  • earthdaily_edc - EarthDaily Constellation

3. Grid Size​

The Dataset will be subdivided into gridded Tasks for Annotation. You can specify the size of a region in meters using the grid_size.

Example Request​

Below is a complete example using curl to create a gridded dataset. Visit the API Endpoint Documentation for a complete schema and sample requests in other languages or libraries.

curl -X POST "https://olmoearth.allenai.org/api/v1/datasets/gridded" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Seattle Urban Analysis",
    "project_id": "7e160260-5a5a-4120-ab33-8ce15998b982",
    "geom": "POLYGON((-122.365581 47.62529, -122.365581 47.655588, -122.319025 47.655588, -122.319025 47.62529, -122.365581 47.62529))",
    "grid_size": 1000,
    "source_time_ranges": [
      {
        "source": "landsat",
        "start_time": "2020-01-01T00:00:00Z",
        "end_time": "2024-01-01T00:00:00Z",
        "count": 3
      },
      {
        "source": "sentinel2",
        "start_time": "2020-01-01T00:00:00Z",
        "end_time": "2024-01-01T00:00:00Z",
        "count": 5
      }
    ]
  }'

Checking Dataset Status​

The dataset will progress through several stages as it builds:

  • pending - Dataset creation has been queued
  • acquiring - Satellite imagery is being acquired
  • ingesting - Data is being processed and ingested
  • completed - Dataset is ready for use

You can monitor the dataset progress using GET /api/v1/datasets/{dataset_id}.

Notes​

  • Dataset creation is an asynchronous process that may take hours depending on the area size and number of images requested
  • The combined geometry of all samples cannot exceed certain size limits