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](https://developers.google.com/agricultural-understanding/reference/rest).

## 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](https://developers.google.com/agricultural-understanding/api/request-format#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](https://developers.google.com/agricultural-understanding/reference/rest/v1/errors).

## 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)](https://datatracker.ietf.org/doc/html/rfc7946).

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](https://maps.google.com/pluscodes) 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](https://developers.google.com/agricultural-understanding/understanding-data#alu-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](https://developers.google.com/agricultural-understanding/understanding-data#amed-confidence).
- **`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](https://developers.google.com/agricultural-understanding/understanding-data#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](https://developers.google.com/agricultural-understanding/api/complete-examples/basic-retrieval)
example.