Earth Swarm
Data and API

The data, for science and for business

Everything on this site comes from a public JSON API. Researchers use it free; companies pay for site monitoring.

Access tiers

No key

Public

  • What this website uses
  • Validated finds, 72 hours or more after they were made
  • Positions to a 0.01 degree grid
  • 2,000 requests a day per address
Free

Research

  • For universities and research institutions, with an institutional email address
  • Non-commercial use only; cite Earth Swarm
  • Positions to a 0.001 degree grid
  • 10,000 requests a day

Apply for research access

Paid

Commercial

  • Site level monitoring of your own land
  • Change metrics between seasons and years
  • Bulk export and higher limits
  • A service level agreement

Tell us about your sites

Under agreement

Verifier

  • For accredited validation and verification bodies
  • Full precision, every validation status
  • The signed receipt of every find, to check against published Merkle roots

Sensitive species are never available at better than a 0.2 degree grid through the public, research or commercial tiers, and their photos are never published. Full precision goes only to verifiers under agreement.

Licences and citation

Earth Swarm records shared with GBIF carry CC BY-NC 4.0: free for science, while commercial users come through the API rather than reselling the raw records.

GBIF context records shown on this site keep their own licence, either CC0 1.0 or CC BY 4.0, and every one carries its GBIF occurrence link, dataset and rights holder in the API. We import no records under any other licence.

Please cite: Earth Swarm (year). Earth Swarm validated species finds. https://earthswarm.ai, accessed on the date you accessed it.

Endpoint reference

Base address https://earthswarm.ai/v1. Send a key, if you have one, as Authorization: Bearer es_.... Every response is JSON. Errors look like {"error":"E_RATE_LIMITED","message":"..."} with a stable code and a sentence for a person. Each response carries x-ratelimit-limit, x-ratelimit-remaining and x-earthswarm-tier.

Coverage by grid cell

Counts of validated finds and distinct species per cell, for a year and season. GBIF context records come back separately, in context. bbox is minLng,minLat,maxLng,maxLat; season is spring, summer, autumn, winter or all; taxon and cell are optional.

curl -s 'https://earthswarm.ai/v1/coverage?year=2027&season=spring&bbox=-6,49.8,2,56'

Observations

Individual validated finds, coarsened for your tier. Filter by bbox, taxon, from and to (YYYY-MM-DD) and source (earthswarm, gbif or all). Page with limit and offset.

curl -s 'https://earthswarm.ai/v1/observations?bbox=-3.6,50.6,-3.4,50.8&taxon=gbif:9515886&from=2027-03-01&to=2027-05-31' \
  -H 'Authorization: Bearer es_your_key'

Species

curl -s 'https://earthswarm.ai/v1/taxa?q=robin'
curl -s 'https://earthswarm.ai/v1/taxa/gbif:9515886'

Projects, registry and monitoring periods

curl -s 'https://earthswarm.ai/v1/projects'
curl -s 'https://earthswarm.ai/v1/projects/prj_example'
curl -s 'https://earthswarm.ai/v1/registry?q=Acme'
curl -s 'https://earthswarm.ai/v1/periods/per_example'

A closed monitoring period publishes the Merkle root over the receipt hashes of every find made in it, and the leaves, so anyone can check a single find against a number fixed at the time.

Photos

curl -s -o find.jpg 'https://earthswarm.ai/v1/photos/f_...'

Only for validated, published finds of species that are not sensitive.

For the Earth Swarm app

curl -s 'https://earthswarm.ai/v1/keys/evidence'

The public key finds are sealed to. The upload format is fixed by the Earth Swarm find protocol, version 1.

curl -s -X POST 'https://earthswarm.ai/v1/finds/status' \
  -H 'content-type: application/json' \
  -d '{"receipt_hashes":["<64 hex characters>"]}'

Where a surveyor's own finds have got to, for the app's My finds list. Send up to 100 receipt hashes. Each one Earth Swarm holds comes back as {"receipt_hash","status","taxon"}, where status is received, pending, validated or rejected and taxon is the confirmed gbif: identifier, only once validated. A hash Earth Swarm does not hold is left out. Nothing else is ever returned: no position, photo, surveyor, note or validator. A receipt hash cannot be guessed and only the phone that made the find holds it. Metered like every public request.