Get Imagery Tiles
Return before/after satellite basemap tile URLs for a geometry, in one
synchronous call. Use the URLs as XYZ tile templates ({z}/{x}/{y}) in a
slippy map (e.g. Mapbox / Leaflet raster source) to render a before/after
imagery comparison.
The source basemap is selected from the geometry's location: NICFI
(Planet's high-resolution tropical basemaps) where available, falling back to
Sentinel-2 elsewhere. The response's source field tells you which was
used. before_date / after_date are the capture dates of the imagery shown:
NICFI mosaic months, or a Sentinel-2 quarterly mosaic (YYYY-Qn); null if
unknown.
Computed and side-effect-free โ no record is persisted. Responses are cached per organization on the geometry + dates, so repeat requests for the same inputs are served without a fresh upstream call.
Note: the tile URLs are time-limited โ they embed a short-lived imagery session token or grant. Treat them as ephemeral (fetch fresh when rendering), not as durable links to store and share.
โถRequest
โถMethod & Path
POST /imagery/tiles
โถHeaders
x-api-keyโ required.Accept: application/jsonContent-Type: application/json
โถBody
geometry(object, required) โ a GeoJSON geometry (e.g. aPointfor a facility or aPolygonfor a plot). Its location selects the basemap.date_before(string or null, optional) โYYYY-MM-DDdate for the "before" imagery. Defaults to2020-12-01. Sendnullto get the "after" imagery alone, for example to step through a series of dates.date_after(string, optional) โYYYY-MM-DDdate for the "after" imagery. Omit for the latest available imagery.month(string, optional) โYYYY-MM. Outside NICFI coverage, pins the "after" frame to the Sentinel-2 quarterly mosaic holding that month (the newest published quarter if it is not out yet). Outside NICFI both frames are quarterly mosaics: the after frame is otherwise the latest quarter ending on or before its date, and the before frame is the same quarter of the year, so both show one season. NICFI coverage ignores it. Withplot_id, allowed only whendate_beforeis null.
โถResponse
- 200 โ an
imagery_tilesresource (see schema below). Computed, not persisted, so it carries noid. - 400 โ invalid body: missing/invalid
geometry, a bad date format, or an unknown field. - 401 / 403 โ missing or invalid key, or the key lacks
imagery:read. - 404 โ outside NICFI, no Sentinel-2 quarterly mosaic covers the geometry for the frames asked, or none covers it for the baseline (before) frame. Retrying won't help.
- 422 โ outside NICFI, the geometry is too large for Sentinel-2 imagery (wider than 3 degrees).
- 500 โ the imagery tile proxy is not configured on this deployment.
- 502 โ a transient upstream imagery failure (a 5xx, request timeout, or
network error). Safe to retry. (A definitive upstream 4xx is treated as a
server-side
500instead, since retrying won't help.)
โถResponse schema
Only the data payload is described; the meta / links envelope is
documented centrally.
| Field | Type | Description |
|---|---|---|
type | string | Always imagery_tiles. |
attributes.tile_url_before | string | null | XYZ tile URL template for the "before" imagery. null only when date_before was sent as null. |
attributes.tile_url_after | string | XYZ tile URL template for the "after" imagery. |
attributes.source | "nicfi" | "sentinel2" | Basemap used: nicfi (tropics) or sentinel2 (fallback). |
attributes.before_date | string | null | Capture date of the "before" imagery: a day or NICFI mosaic month, or a Sentinel-2 mosaic quarter (YYYY-Qn). null if unknown. |
attributes.after_date | string | null | Capture date of the "after" imagery: a day or NICFI mosaic month, or a Sentinel-2 mosaic quarter (YYYY-Qn). null if unknown. |
Required scope:
imagery:read