Data API

Soil intelligence, built to travel.

A proposed API contract for the data the frontend is prepared to consume. Production endpoints are not yet available.

API availability status

Current provider: mock. The active frontend uses the mock provider until a verified production API base URL is configured.

Proposed endpoints

GET/v1/countries

List country rankings, scores, availability, and update metadata.

GET/v1/countries/{slug}

Retrieve a country profile, indicators, sources, and history.

GET/v1/indicators

List indicator definitions, units, and source categories.

GET/v1/summary

Retrieve global and regional aggregate statistics.

GET/v1/ticker

Retrieve the compact ticker sequence and stable change fields.

Access model

Designed for responsible reuse

Versioned datasets and source metadata

Scoped API keys and documented rate limits

Normalized JSON with explicit nulls for missing values

Structured errors for validation and unavailable data

Response example

{
  "code": "CH",
  "name": "Switzerland",
  "slug": "switzerland",
  "rank": 1,
  "score": 84.7,
  "scoreChange": 0.4,
  "dataAvailability": "complete",
  "measurementDate": "2026-05-26",
  "verificationStatus": "api-normalized"
}

Error example

{
  "error": {
    "code": "validation_failed",
    "message": "Country score must be a number between 0 and 100.",
    "requestId": "req_..."
  }
}

Data model

Core fields consumed by the frontend

Country code

Country name

Slug

Flag reference

Region

Rank

Score

Score change

Indicator values

Measurement date

Source information

Dataset update time

Data availability

Verification status

Indicator catalog currently contains 9 proposed indicator definitions. Production API responses should keep missing values as null rather than fabricating fallback measurements.