Working with Areas of Interest (AOI)

An Area of Interest (AOI) is a geographic region defined by a polygon that you want to analyze using satellite imagery or other geospatial data. In ObservEarth's API, AOIs are represented as GeoJSON polygons and are the foundation for all data retrieval operations.

Each AOI is assigned a unique identifier (UUID) that you'll use to reference it in subsequent API calls. This allows you to:

• Search for satellite imagery covering your AOI
• Calculate statistics for your AOI
• Generate visualizations of your AOI
• Extract data for your AOI

POST

https://observearth.com/api/geometry/

Description

This endpoint allows you to create a new AOI by providing a GeoJSON polygon. The API will validate the geometry and return a unique identifier that you can use in subsequent requests.

Request Body

The request body should contain a valid GeoJSON polygon:

{
  "name": "My Farm Field",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [13.404, 52.520],
        [13.414, 52.520],
        [13.414, 52.525],
        [13.404, 52.525],
        [13.404, 52.520]
      ]
    ]
  }
}

Response

Upon successful creation, the API returns the created AOI with its unique identifier:

{
"id": "4f6cbd32-6724-41be-8449-baec160ccfae",
"type": "Feature",
"geometry": {
    "type": "Polygon",
    "coordinates": [
    [
        [
        13.404,
        52.52
        ],
        [
        13.414,
        52.52
        ],
        [
        13.414,
        52.525
        ],
        [
        13.404,
        52.525
        ],
        [
        13.404,
        52.52
        ]
    ]
    ]
},
"properties": {
    "user": "ad999f37-921c-44fe-b52c-806ce3374372",
    "name": "sample poi",
    "area": 377456.2402341795,
    "created_at": "2025-05-28T09:13:19.029302Z"
}
}

Best Practices

• Keep your AOIs reasonably sized (ideally under 100 hectares) for optimal performance
• Use meaningful names and descriptions to easily identify your AOIs later
• Ensure your coordinates are in the correct order: [longitude, latitude]
• Make sure your polygon is closed (first and last coordinates are identical)

Code Example

import requests
import json

api_key = "your_api_key_here"
url = "https://observearth.com/api/geometry/"

payload = {
    "name": "My Farm Field",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [13.404, 52.520],
          [13.414, 52.520],
          [13.414, 52.525],
          [13.404, 52.525],
          [13.404, 52.520]
        ]
      ]
    }
  }

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
aoi = response.json()

# Save the AOI ID for future use
aoi_id = aoi["id"]
print(f"Created AOI with ID: {aoi_id}")

const apiKey = "your_api_key_here";
const url = "https://observearth.com/api/geometry/";

const payload = {
    "name": "My Farm Field",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [13.404, 52.520],
          [13.414, 52.520],
          [13.414, 52.525],
          [13.404, 52.525],
          [13.404, 52.520]
        ]
      ]
    }
  };

fetch(url, {
    method: "POST",
    headers: {
        "X-API-Key": apiKey,
        "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(aoi => {
    // Save the AOI ID for future use
    const aoiId = aoi.id;
    console.log(`Created AOI with ID: ${aoiId}`);
})
.catch(error => console.error("Error creating AOI:", error));

GET

https://observearth.com/api/geometry/?detail=false

Description

This endpoint returns a list of all AOIs that you have created. You can use this to find the IDs of your existing AOIs. You can use `default` to get a summary of each AOI, or set `detail=true` to get full details including geometry.

Response

[
{
    "id": "956e8034-1532-4de7-b3bc-9e4ba296c68a",
    "area": 264462.1258524544,
    "name": "sdf",
    "created_at": "2021-05-12T10:29:34.973031Z"
},
{
    "id": "e2682801-b751-4022-8510-90b6a920a3c1",
    "area": 30125.72196420604,
    "name": "gj",
    "created_at": "2023-02-13T08:45:57.236272Z"
},
{
    "id": "99e297b1-6f2f-44ac-91e0-e6139057f325",
    "area": 60039.261321758495,
    "name": "dummy data",
    "created_at": "2025-01-11T09:32:15.087059Z"
},
{
    "id": "728ddcc8-976f-4745-b0dd-11ddb6610c23",
    "area": 18121.562260728268,
    "name": "Kt",
    "created_at": "2023-01-14T03:08:53.358183Z"
},
{
    "id": "ef802a05-d81f-40f0-9171-baa7ccd9e7da",
    "area": 35368.30672888984,
    "name": "bihar",
    "created_at": "2022-05-14T03:39:46.153651Z"
}]

Code Example

import requests

api_key = "your_api_key_here"
url = "https://observearth.com/api/geometry/?detail=false"

headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers)
data = response.json()

# Print all AOIs
for aoi in data["results"]:
    print(f"ID: {aoi['id']}, Name: {aoi['name']}, Area: {aoi['area']} hectares")

const apiKey = "your_api_key_here";
const url = "https://observearth.com/api/geometry/?detail=false"";

fetch(url, {
    method: "GET",
    headers: {
        "X-API-Key": apiKey
    }
})
.then(response => response.json())
.then(data => {
    // Print all AOIs
    data.results.forEach(aoi => {
        console.log(`ID: ${aoi.id}, Name: ${aoi.name}, Area: ${aoi.area} hectares`);
    });
})
.catch(error => console.error("Error retrieving AOIs:", error));

GET

https://observearth.com/api/geometry/{id}/

Description

This endpoint returns detailed information about a specific AOI, including its full geometry.

Path Parameters

Response

{
"id": "728ddcc8-9768-4745-b0dd-11ddb6610c23",
"type": "Feature",
"geometry": {
    "type": "Polygon",
    "coordinates": [
    [
        [
        76.18930632049795,
        12.728724888219546
        ],
        [
        76.1889955503516,
        12.727804478220094
        ],
        [
        76.19040251462233,
        12.727402200073627
        ],
        [
        76.1907384000703,
        12.728442923273334
        ],
        [
        76.18930632049795,
        12.728724888219546
        ]
    ]
    ]
},
"properties": {
    "user": "ad999f37-9q1c-44fe-b52c-806ce3374372",
    "name": "sample",
    "area": 18121.562260728268,
    "created_at": "2025-05-14T03:08:53.358183Z"
}
}

Code Example

import requests

api_key = "your_api_key_here"
aoi_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://observearth.com/api/geometry/{aoi_id}/"

headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers)
aoi = response.json()

print(f"AOI Name: {aoi['name']}")
print(f"Area: {aoi['area']} hectares")

const apiKey = "your_api_key_here";
const aoiId = "123e4567-e89b-12d3-a456-426614174000";
const url = `https://observearth.com/api/geometry/${aoiId}/`;

fetch(url, {
    method: "GET",
    headers: {
        "X-API-Key": apiKey
    }
})
.then(response => response.json())
.then(aoi => {
    console.log(`AOI Name: ${aoi.name}`);
    console.log(`Area: ${aoi.area} hectare`);
})
.catch(error => console.error("Error retrieving AOI:", error));

DELETE

https://observearth.com/api/geometry/{id}/

Description

This endpoint permanently deletes an AOI. This action cannot be undone.

Path Parameters

Response

A successful deletion returns a 204 No Content status with no response body.

Code Example

import requests

api_key = "your_api_key_here"
aoi_id = "123e4567-e89b-1qd3-a456-426614174000"
url = f"https://observearth.com/api/geometry/{aoi_id}/"

headers = {
    "X-API-Key": api_key
}

response = requests.delete(url, headers=headers)

if response.status_code == 204:
    print(f"AOI {aoi_id} successfully deleted")
else:
    print(f"Error deleting AOI: {response.status_code}")

const apiKey = "your_api_key_here";
const aoiId = "123e4567-e89b-12d3-a456-426614174000";
const url = `https://observearth.com/api/geometry/${aoiId}/`;

fetch(url, {
    method: "DELETE",
    headers: {
        "X-API-Key": apiKey
    }
})
.then(response => {
    if (response.status === 204) {
        console.log(`AOI ${aoiId} successfully deleted`);
    } else {
        console.error(`Error deleting AOI: ${response.status}`);
    }
})
.catch(error => console.error("Error deleting AOI:", error));

Once you have created an AOI, you can use its ID to access various data sources through our other APIs:

Satellite Imagery

• Sentinel-2 - Optical imagery at 10m resolution
• Sentinel-1 - Radar imagery
• Landsat - Long-term optical imagery
• MODIS - Daily global coverage

Other Data Sources

• Weather - Current, forecast, and historical weather data
• Digital Elevation Model (DEM) - Elevation data and contour lines

Size Considerations

• Keep AOIs under 100 hectares for optimal performance
• For larger areas, consider dividing them into multiple smaller AOIs
• Very small AOIs (under 0.01 hectares) may not contain enough pixels for meaningful analysis

Organization

• Use descriptive names and detailed descriptions
• Consider including location information in the name (e.g., "Farm Field - North County")
• For time series analysis, create a single AOI rather than multiple similar ones

Geometry Tips

• Ensure your polygons are valid (no self-intersections)
• Keep the number of vertices reasonable (under 100) for better performance
• For complex shapes, consider simplifying the geometry while maintaining accuracy

Now that you understand how to work with Areas of Interest, you can:

• Learn how to access Sentinel-2 imagery
• Explore weather data for your AOIs
• Calculate vegetation indices
• Perform time series analysis