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/json
  • Content-Type: application/json

Body

  • geometry (object, required) โ€” a GeoJSON geometry (e.g. a Point for a facility or a Polygon for a plot). Its location selects the basemap.
  • date_before (string or null, optional) โ€” YYYY-MM-DD date for the "before" imagery. Defaults to 2020-12-01. Send null to get the "after" imagery alone, for example to step through a series of dates.
  • date_after (string, optional) โ€” YYYY-MM-DD date 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. With plot_id, allowed only when date_before is null.

Response

  • 200 โ€” an imagery_tiles resource (see schema below). Computed, not persisted, so it carries no id.
  • 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 500 instead, since retrying won't help.)

Response schema

Only the data payload is described; the meta / links envelope is documented centrally.

FieldTypeDescription
typestringAlways imagery_tiles.
attributes.tile_url_beforestring | nullXYZ tile URL template for the "before" imagery. null only when date_before was sent as null.
attributes.tile_url_afterstringXYZ tile URL template for the "after" imagery.
attributes.source"nicfi" | "sentinel2"Basemap used: nicfi (tropics) or sentinel2 (fallback).
attributes.before_datestring | nullCapture date of the "before" imagery: a day or NICFI mosaic month, or a Sentinel-2 mosaic quarter (YYYY-Qn). null if unknown.
attributes.after_datestring | nullCapture 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