Response format

This page describes common response structures, HTTP status codes, and GeoJSON formatting.

Common output structures

Most API endpoints return data using a common response structure.

This page explains these shared payload properties, like the dataVersion schema and the GeoJSON format, along with how to interpret HTTP response codes across the API. For endpoint-specific requests and responses, consult the REST API reference.

Common HTTP response codes

The API returns standard HTTP status codes to indicate the success or failure of an API request. Here are the most common statuses you might encounter:

  • 200 OK: The request was successfully fulfilled and the expected payload is returned in the response body.
  • 400 Bad Request: The request contains invalid syntax or parameters. This status is returned if required fields are missing or if an invalid S2 cell level is provided (requests require level 13 S2 cells).
  • 401 Unauthorized: Authentication failed. Ensure your request includes a valid API key.
  • 403 Forbidden: Your client does not have sufficient privileges for this request.
  • 404 Not Found: The requested resource or data coverage does not exist. Returned when querying locations without data coverage (such as non-agricultural or urban regions). See non-agricultural areas to include these areas in the request.
  • 500 Internal Server Error: A server-side error occurred. Retry the request using exponential backoff.

Error statuses are generally accompanied by a response body with additional information about the error. For a detailed list of possible error reasons, see the service error catalog.

Response data types and substructures

For endpoints that retrieve spatial agricultural intelligence, the response payload is wrapped inside a top-level key corresponding to the endpoint ("landscape" for lookupLandscape or "monitoredLandscape" for monitorLandscape) and includes all features in the level 13 S2 cell corresponding to the request location specifier. Within that wrapper:

  • dataVersion: Contains versioning information about the underlying machine learning models and maps (for example, "version": "1").
  • geojson: A JSON string enclosing the geographical boundaries and properties of requested landscape features. The payload uses a stringified JSON property to comply with Protobuf schema rules. Applications must parse this string into a GeoJSON FeatureCollection before processing features.

GeoJSON and FeatureCollection format

Geographical features are structured following the GeoJSON specification (RFC 7946).

Once parsed, the geojson payload is a single object of type FeatureCollection containing an array of features. Each Feature represents an individual landscape element using WGS 84 coordinates.

Agricultural landscape features

Every Feature in the GeoJSON FeatureCollection includes spatial geometry alongside metadata in properties and id.

Feature ID

The id of a Feature is a string matching the Plus Code of the feature's centroid.

Feature properties

The properties object provides semantic attributes about the feature detected by the model:

  • alu_type: Physical landscape cover type. Values include field, farm_pond, other_water, dug_well, and trees.
  • area_sq_m: Total surface area in square meters.
  • class_confidence: Floating-point score between 0.0 and 1.0 representing classification confidence.
  • capture_timestamp_sec: Unix epoch timestamp in seconds of the source imagery.

When calling monitorLandscape, field features additionally contain a monitoring_prediction array:

  • start_timestamp_sec / end_timestamp_sec: Integer bounds for the detected agricultural season.
  • crop_1 / conf_1: Most likely crop classification and confidence score.
  • crop_2 / conf_2: (Optional) Second most likely crop classification and confidence score.
  • crop_3 / conf_3: (Optional) Third most likely crop classification and confidence score.

For the full list of supported crop types, see Supported crops.

Example response snippet

The following excerpt shows a standard parsed GeoJSON structure:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "7M2JHHF6+MFWC",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [ ... ]
      },
      "properties": {
        "alu_type": "trees",
        "area_sq_m": 149.7001,
        "class_confidence": 1.0,
        "capture_timestamp_sec": 1697353200
      }
    }
  ]
}

For complete response payload code examples, see the Basic retrieval example.