Skip to main content

​
Overview

Use this endpoint to generate an embeddable Earth view for your app. api.embed.earth returns an embedUrl and scene metadata you can render in an iframe.

​
Endpoint

POST https://api.embed.earth/v1/geospatial/embed

​
Authentication

Send your API key in the Authorization header. 
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

​
Request body

FieldTypeRequiredDescription
locationobjectYesThe map center point.
location.latnumberYesLatitude in decimal degrees.
location.lngnumberYesLongitude in decimal degrees.
zoomnumberNoZoom level from 1 to 20.
pitchnumberNoCamera pitch in degrees from 0 to 85.
bearingnumberNoCamera bearing in degrees from 0 to 360.
layersarray[string]NoData layers to render, such as terrain, satellite, or roads.
markersarray[object]NoMarker objects shown on the map.
markers[].idstringYesStable marker ID.
markers[].latnumberYesMarker latitude in decimal degrees.
markers[].lngnumberYesMarker longitude in decimal degrees.
markers[].labelstringNoLabel displayed in the tooltip.
expiresInstringNoSigned URL lifetime such as 15m or 1h.

​
Example request

curl -X POST "https://api.embed.earth/v1/geospatial/embed" \
  -H "Authorization: Bearer $EMBED_EARTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": { "lat": 37.7749, "lng": -122.4194 },
    "zoom": 11,
    "pitch": 35,
    "bearing": 10,
    "layers": ["terrain", "roads"],
    "markers": [
      {
        "id": "city-hall",
        "lat": 37.7793,
        "lng": -122.4192,
        "label": "San Francisco City Hall"
      }
    ],
    "expiresIn": "1h"
  }'

​
Example response

{
  "id": "emb_01JY8Y4X2N2F7M4CE0JZ9P8A1Q",
  "embedUrl": "https://api.embed.earth/e/emb_01JY8Y4X2N2F7M4CE0JZ9P8A1Q?sig=mock_signature",
  "expiresAt": "2026-03-30T14:00:00Z",
  "scene": {
    "location": { "lat": 37.7749, "lng": -122.4194 },
    "zoom": 11,
    "pitch": 35,
    "bearing": 10,
    "layers": ["terrain", "roads"]
  }
}

​
Error response

{
  "error": {
    "code": "invalid_location",
    "message": "location.lat must be between -90 and 90."
  }
}