TerraByte API

Search the Earth. In one request.

Send a natural-language query to the same search system behind the TerraByte dashboard. Receive ranked imagery matches with coordinates, source year, and a relevance score.

Natural-language search across the imagery archive
Ranked results with latitude, longitude, year, and score
Self-serve API keys from the portal dashboard

Open TerraByte Search Request API access

Live endpoint REST / JSON

Request ready POST /v1/search

# Search the imagery archive
curl https://portal.terrabyte.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TERRABYTE_API_KEY" \
  -d '{
    "text": "oil storage tanks",
    "top_k": 50
  }'

{
  "points": [
    {
      "lat": 32.7831,
      "lon": -96.8067,
      "score": 0.74,
      "year": 2022
    }
  ]
}

Status200 OK

Formatapplication/json

ResultRanked points

Base URLhttps://portal.terrabyte.ai

EndpointPOST /v1/search

AuthenticationAPI key (Bearer)

ResponseJSON · ranked coordinates

POST

/v1/search

Search the imagery archive with a plain-English description and receive the highest-ranking geographic matches.

Request bodyapplication/json

textrequired
Natural-language description of the place or visual pattern to find.
top_koptional
Maximum number of ranked matches to return.

ResponseRanked point objects

ididentifier
The matching imagery record.
lat / loncoordinates
The geographic center of the match.
scorerelevance
The match score used to order results.
yearvintage
The source imagery year returned with the match.

Reference

What comes back, and what can go wrong?

Every response is JSON. A successful search returns points, each with lat, lon, a relevance score (a ranking signal, not a calibrated probability), and the imagery’s acquisition year. Request fields: text (required, up to 500 characters), top_k (1–200, default 100), an optional bbox as [minLon, minLat, maxLon, maxLat], and parse_nl (default true) to let TerraByte resolve places named in your query. The full contract is machine-readable at /developers/openapi.json.

Status	Meaning	Body
200	Ranked matches	`{ "points": […] }`
400	The request body failed validation	`{ "error": "invalid request body" }`
401	Missing or invalid API key	`{ "error": "missing Authorization: Bearer <api key>" }`
403	The account’s email is not verified yet	`{ "error": "email_not_verified" }`
429	Quota exhausted or rate limited — `Retry-After` says when to try again	`{ "error": "quota_exceeded", "scope": "daily", "limit": 20, "used": 20, "resets_at": … }`
502	The search backend errored	`{ "error": "gateway error" }`

Free accounts can run 20 searches a day and 100 a month. Need more? See pricing or talk to the team.

From query to evidence

How does a query become evidence?

Describe.

Send the place, object, or visual pattern you are trying to find in ordinary language.

Rank.

TerraByte searches the imagery archive and orders matches by visual relevance.

Integrate.

Use the returned coordinates, scores, and years in your own application or review flow.