Trees and green areas API

1. Accept your invitation

Open the invitation link, choose Generate credentials, and save the client ID and secret in your backend’s secret manager. The invitation can be used once and expires after seven days. Credentials appear once. Anyone holding the invitation can redeem it: keep the link private. The contact email is an administrative label, not an email verification mechanism. Never embed credentials in frontend code or a mobile app.

2. Get an access token

Use HTTPS in production. OAuth client credentials supports HTTP Basic or form client_id/client_secret. Tokens last up to 15 minutes. Reuse a token until expiry, then request another; there are no refresh tokens.

# Set ATLAS_ORIGIN to the Atlas website URL.
# Read credentials from your secret manager into these environment variables.
curl --user "$ATLAS_CLIENT_ID:$ATLAS_CLIENT_SECRET" \
  --data 'grant_type=client_credentials' \
  "$ATLAS_ORIGIN/partner/v1/oauth/token"

The response includes access_token, token_type, expires_in and scope. Keep tokens out of URLs and logs.

3. Discover your collections and retrieve data

curl -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  "$ATLAS_ORIGIN/partner/v1/collections"

curl -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  "$ATLAS_ORIGIN/partner/v1/collections/trees/items?limit=100&bbox=21.1,42.6,21.2,42.7"

curl -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  "$ATLAS_ORIGIN/partner/v1/collections/green-areas/items?limit=100"

Items are GeoJSON FeatureCollections using WGS84 longitude, latitude. Fields vary by location and grant. Every feature has a stable ID, updated_at and version. Geometry is null when your grant excludes it. Bbox filtering requires geometry permission for every queried location; add location_id to narrow the query.

Retrieve one feature at /partner/v1/collections/trees/items/FEATURE_UUID or the equivalent green-areas path. Only verified records in active, granted locations are available. Other collections are denied.

Available attributes

Administrators approve each field separately. A missing property means it is not granted; null means no value is recorded. IDs, updated_at and version are always included. No private notes, observer identities, raw provenance or observation history are shared.

Measurements use the latest nonempty observation for each field; health and DBH fall back to an assigned tree attribute. Measurements may therefore have different observation dates. last_observed_at is the newest observation overall, not a date for every measurement. Height and canopy diameter use meters; trunk diameter, DBH and circumference use centimeters; canopy area uses square meters. Category values such as edible are recorded strings, not guaranteed booleans.

4. Download larger datasets

Follow links with rel=next, retaining the same Authorization header. Resolve relative links against the Atlas origin. Do not send credentials to a different host. Pagination uses stable UUID cursors without deep offsets or full-dataset counts. Each response contains at most your configured page size.

Download the Python collection downloader. It uses only the Python standard library, saves one complete GeoJSON file, refreshes tokens, respects quotas and processes one page at a time.

python3 atlas_download.py --credentials green-atlas-api-credentials.json   --collection trees --output trees.geojson

Map applications can request /partner/v1/collections/trees/tiles/Z/X/Y.pbf or the green-areas equivalent. These use the same bearer tokens and quotas. Only locations granting geometry are included. Tile attributes follow each location’s field policy; geometry is clipped and simplified for display. A tile containing more than 10,000 features returns 413: zoom in.

For larger collections, create a private background export, poll its status, then download it with the same bearer token. The file is a consistent snapshot and includes the approved attributes, license metadata and sync_cursor.

curl -X POST -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' --data '{"collection":"trees"}' \
  "$ATLAS_ORIGIN/partner/v1/exports"

curl -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  "$ATLAS_ORIGIN/partner/v1/exports/EXPORT_UUID"

curl -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  "$ATLAS_ORIGIN/partner/v1/exports/EXPORT_UUID/download" -o trees.geojson

Export statuses: queued, running, ready or failed. Files expire after 24 hours. Limits: one active job, five jobs per rolling 24 hours, 250 MiB per file and a 15-minute processing limit. For a failed oversized export, use bounded GeoJSON pages. Another client cannot retrieve your export; suspension, revocation or a policy/license change blocks download. A running download may finish.

Do not treat map tiles as full-resolution source data.

5. Keep your local copy synchronized

First call the changes endpoint without after to obtain cursor and policy_revision. Keep both, download all GeoJSON pages, then replay changes starting at that cursor. Alternatively, obtain policy_revision before requesting a background export and replay from its sync_cursor.

GET /partner/v1/collections/trees/changes
GET /partner/v1/collections/trees/changes?after=CURSOR&policy_revision=REVISION&limit=100

Use the same bearer header. Apply upsert by stable feature ID and remove by ID. Continue from the returned cursor until has_more is false; save the cursor only after applying that page. Replayed events are safe to apply again. Upserts contain the currently approved feature, rather than historical values. Changes include edits, new verification, deletion and verification withdrawal, plus species and observation updates.

HTTP 409 with resync_required means your access policy or license changed: discard the local copy and perform a full download. HTTP 403 can mean that collection access was withdrawn: stop synchronization and remove that local collection. New grants require a full download. updated_since remains available but cannot detect removals. The change journal starts when this feature was installed; initial full downloads are always required. There is no bbox filter on changes, so reconcile spatial subsets locally.

Errors and access changes

• 401: token or credentials invalid, expired, suspended or revoked.
• 403: collection, location or operation not granted.
• 404: feature unavailable within your scope.
• 409: export not ready or synchronization requires a full download.
• 410: export expired.
• 413: geometry page or tile too large; reduce the page size or zoom in.
• 422: invalid bounds, cursor, timestamp or page size.
• 429: quota reached; wait for Retry-After seconds.
• 503: administrator has disabled the partner API.

Administrators can change grants, suspend access, revoke it permanently, or issue a replacement invitation. Replacement invitations invalidate existing credentials and tokens. Data requests count toward per-minute and daily UTC quotas, including requests that fail validation after authentication. Token requests have a separate limit of 30 attempts per minute per client.

License and attribution

Check fields_by_location in collection metadata for data_license, attribution and license_status. A declared license applies to the corresponding location and collection. Preserve its attribution with your outputs. When license_status is not-declared, contact the administrator before redistribution; free access is not a redistribution license. Source-derived data may carry additional obligations. The application’s GPL software license does not set the dataset license.

The API uses OGC-style collection routes and GeoJSON; it does not claim certified OGC API Features conformance.