Area Management

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:

• POST /api/v1/areas
• GET /api/v1/areas/{area_id}
• POST /api/v1/areas/search
• PUT /api/v1/areas/{area_id}
• DELETE /api/v1/areas/{area_id}

This guide explains how to create and manage areas in OlmoEarth Studio. Areas define spatial regions that can be used for creating predictions and running inference on specific geographic locations.

What is an Area?

An area is a GeoJSON Polygon or MultiPolygon that represents a geographic region of interest. Areas define spatial regions where you can run predictions and inference operations.

Prerequisites

API Token

To get your API Token, see Authentication

Creating an Area

Create a new area using POST /api/v1/areas.

Request Format

{
  "name": "Study Region Name",
  "geom": {
    "type": "Polygon",
    "coordinates": [[
      [longitude, latitude],
      [longitude, latitude],
      [longitude, latitude],
      [longitude, latitude],
      [longitude, latitude]
    ]]
  }
}

Example: Create a Simple Polygon Area

This example creates an area covering a research site in Kenya:

curl -X POST "https://olmoearth.allenai.org/api/v1/areas" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nandi County Research Site",
    "geom": {
      "type": "Polygon",
      "coordinates": [[
        [35.1000, 0.1000],
        [35.2000, 0.1000],
        [35.2000, 0.2000],
        [35.1000, 0.2000],
        [35.1000, 0.1000]
      ]]
    }
  }'

Example: Create a MultiPolygon Area

For non-contiguous regions (e.g., multiple study sites):

curl -X POST "https://olmoearth.allenai.org/api/v1/areas" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Multiple Field Sites",
    "geom": {
      "type": "MultiPolygon",
      "coordinates": [
        [[[35.1000, 0.1000], [35.1500, 0.1000], [35.1500, 0.1500], [35.1000, 0.1500], [35.1000, 0.1000]]],
        [[[35.3000, 0.3000], [35.3500, 0.3000], [35.3500, 0.3500], [35.3000, 0.3500], [35.3000, 0.3000]]]
      ]
    }
  }'

Response

{
  "records": [
    {
      "id": "f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Nandi County Research Site",
      "geom": {
        "type": "Polygon",
        "coordinates": [[...]]
      },
      "created_time": "2024-01-15T10:30:00Z",
      "updated_time": "2024-01-15T10:30:00Z"
    }
  ]
}

Getting a Single Area

Retrieve a specific area by ID using GET /api/v1/areas/{area_id}.

Example Request

curl -X GET "https://olmoearth.allenai.org/api/v1/areas/f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Returns the area with its full GeoJSON geometry:

{
  "records": [
    {
      "id": "f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Nandi County Research Site",
      "geom": {
        "type": "Polygon",
        "coordinates": [[
          [35.1000, 0.1000],
          [35.2000, 0.1000],
          [35.2000, 0.2000],
          [35.1000, 0.2000],
          [35.1000, 0.1000]
        ]]
      },
      "created_time": "2024-01-15T10:30:00Z",
      "updated_time": "2024-01-15T10:30:00Z"
    }
  ]
}

Searching for Areas

Search and filter areas using POST /api/v1/areas/search.

This endpoint supports advanced filtering and returns areas without geometries for improved performance. Use the GET /areas/{area_id} endpoint to retrieve the full geometry for a specific area.

Search Parameters

• name (optional) - Filter by area name (partial match)
• limit (optional) - Number of results to return (default: 50)
• offset (optional) - Offset for pagination (default: 0)

Example: Search All Areas

curl -X POST "https://olmoearth.allenai.org/api/v1/areas/search" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "offset": 0
  }'

Example: Search by Name

curl -X POST "https://olmoearth.allenai.org/api/v1/areas/search" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kenya",
    "limit": 10
  }'

Response

Returns areas without geometries for faster responses:

{
  "records": [
    {
      "id": "f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Nandi County Research Site",
      "created_time": "2024-01-15T10:30:00Z",
      "updated_time": "2024-01-15T10:30:00Z"
    },
    {
      "id": "a2b3c4d5-e6f7-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Kenya Coastal Region",
      "created_time": "2024-01-14T08:15:00Z",
      "updated_time": "2024-01-14T08:15:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

note

The search endpoint excludes geometries to improve performance when listing many areas. To get the full geometry, use GET /api/v1/areas/{area_id}.

Updating an Area

Update an existing area using PUT /api/v1/areas/{area_id}.

You can update:

• name - Area name
• geom - Area geometry (Polygon or MultiPolygon)

Example: Update Area Name

curl -X PUT "https://olmoearth.allenai.org/api/v1/areas/f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nandi County - Expanded Research Site"
  }'

Example: Update Area Geometry

curl -X PUT "https://olmoearth.allenai.org/api/v1/areas/f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "geom": {
      "type": "Polygon",
      "coordinates": [[
        [35.0500, 0.0500],
        [35.2500, 0.0500],
        [35.2500, 0.2500],
        [35.0500, 0.2500],
        [35.0500, 0.0500]
      ]]
    }
  }'

Response

{
  "records": [
    {
      "id": "f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Nandi County - Expanded Research Site",
      "geom": {
        "type": "Polygon",
        "coordinates": [[...]]
      },
      "created_time": "2024-01-15T10:30:00Z",
      "updated_time": "2024-01-15T14:22:00Z"
    }
  ]
}

Deleting an Area

Delete an area using DELETE /api/v1/areas/{area_id}.

warning

Areas cannot be deleted if they are used in any predictions. This prevents accidental data loss.

Example Request

curl -X DELETE "https://olmoearth.allenai.org/api/v1/areas/f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "status": "deleted",
  "records": [
    {
      "id": "f1e2d3c4-b5a6-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Nandi County Research Site",
      "geom": {
        "type": "Polygon",
        "coordinates": [[...]]
      },
      "created_time": "2024-01-15T10:30:00Z",
      "updated_time": "2024-01-15T14:22:00Z"
    }
  ]
}

Geometry Requirements

Supported Geometry Types

Areas must be polygons representing spatial regions:

• Polygon - Single contiguous region
• MultiPolygon - Multiple non-contiguous regions

note

Areas do not support Point, LineString, or other geometry types. Areas represent 2D regions for spatial analysis.

Coordinate System

All coordinates must be in WGS84 (EPSG:4326):

• Longitude: -180 to 180
• Latitude: -90 to 90
• Format: [longitude, latitude]

Polygon Rules

Polygons must follow GeoJSON specifications: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6

Complete API Reference

For detailed schemas, parameters, and examples in multiple languages, visit:

• Create Area
• Get Area
• Search Areas
• Update Area
• Delete Area

See Also

• Upload GeoJSON Dataset - Create datasets with area geometries
• Authentication - Get your API token