Skip to content

introduction.mdx

Latest commit

 

History

History
229 lines (183 loc) · 5.2 KB

introduction.mdx

File metadata and controls

229 lines (183 loc) · 5.2 KB
Raw
title API Introduction
description REST API for querying signals, creating alerts, exporting audiences, and triggering analyses

Overview

The Evoteli exposes a RESTful JSON API for querying time-series signals, creating alerts, exporting audiences, and triggering Earth Engine tasks.

Base URL

https://api.evoteli.com/v1

Authentication

All API requests require an OAuth 2.0 Bearer Token obtained via your client credentials.

Obtaining a Token

curl -X POST https://auth.evoteli.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

Include the token in the Authorization header:

curl -X POST https://api.evoteli.com/v1/signals:query \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API Endpoints

Query time-series metrics with spatial and temporal filters Create threshold and anomaly-based alerts Export filtered audiences to ad platforms Trigger insolation, NDVI, and DEM analyses Fetch source attribution and model lineage

Rate Limits

Tier Requests per Minute Burst
Starter 60 100
Growth 300 500
Enterprise 1000 2000

Rate Limit Headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1699296000

Error Handling

All errors return standard HTTP status codes with JSON bodies:

Example Error Response:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: site_id or polygon_id",
    "details": {
      "param": "site_id",
      "suggestion": "Provide at least one of: site_id, polygon_id"
    }
  }
}

Common Error Codes

Code HTTP Status Description
INVALID_REQUEST 400 Malformed request or missing parameters
UNAUTHORIZED 401 Invalid or expired token
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
RATE_LIMIT_EXCEEDED 429 Too many requests
INTERNAL_ERROR 500 Server error

Pagination

List endpoints support cursor-based pagination:

Request:

GET /sites?limit=100&cursor=eyJpZCI6MTIzNH0

Response:

{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6MTMzNH0",
  "has_more": true
}

Data Types

Timestamps

All timestamps use ISO 8601 format in UTC:

2025-11-06T14:30:00Z

Geometries

Polygons and points use GeoJSON format (SRID 4326):

{
  "type": "Polygon",
  "coordinates": [[
    [-84.3880, 33.7490],
    [-84.3870, 33.7490],
    [-84.3870, 33.7480],
    [-84.3880, 33.7480],
    [-84.3880, 33.7490]
  ]]
}

Versioning

The API uses URL-based versioning (/v1, /v2). Breaking changes will increment the major version. Deprecated endpoints will be supported for at least 12 months.

SDKs

```bash pip install geointel-sdk ``` ```bash npm install @geointel/sdk ``` ```bash go get github.com/geointel/sdk-go ```

Quickstart Example

Python:

from geointel import Client

client = Client(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Query occupancy for last 24 hours
response = client.signals.query(
    site_id="ATL-CTF-001",
    metrics=["occupancy", "queue_len"],
    time_from="2025-11-05T00:00:00Z",
    time_to="2025-11-06T00:00:00Z",
    rollup="15m"
)

for row in response.rows:
    print(f"{row.ts}: {row.metric}={row.value} ({row.unit})")

Support

Next Steps

Learn how to query time-series metrics Set up threshold and anomaly alerts Generate audience exports for ad platforms Deep dive into OAuth 2.0 authentication