Request format

When querying data from the Agricultural Understanding API, you identify a geographic location using the locationSpecifier structure. The API supports specifying locations using either geographic point coordinates or level 13 S2 cell IDs.

This page explains how to format your requests with these location specifiers and additional request parameters.

Using the location specifier

The locationSpecifier object requires populating one location format: point coordinates or an S2 cell ID.

An API request payload contains the locationSpecifier along with optional configuration parameters such as dataVersion or parameters specific to the lookupLandscape endpoint:

{
  "locationSpecifier": {
    "s2CellId": "4306523180387794944"
  },
  "dataVersion": {
    "version": "1"
  }
}

Targeting with coordinates

To request data for a point location, use the coordinates field. This field takes a LatLng object with numeric latitude and longitude values conforming to WGS 84:

  • latitude: Number in the range [-90.0, 90.0].
  • longitude: Number in the range [-180.0, 180.0].

Example passing coordinates:

{
  "locationSpecifier": {
    "coordinates": {
      "latitude": 18.624,
      "longitude": 73.076
    }
  }
}

Targeting with S2 cells

The API organizes spatial data into grid cells using the S2 geometry library. By specifying an s2CellId, you retrieve features within that cell.

For landscape data, queries require level 13 S2 cell IDs (representing regions approximately 1 km x 1 km). Provide s2CellId as a 64-bit unsigned decimal integer string (for example, "4306523180387794944"). For more information on S2 cells, read the Understanding the data section.

Example passing s2CellId:

{
  "locationSpecifier": {
    "s2CellId": "4306523180387794944"
  }
}

Data version

The dataVersion parameter lets you query a specific version of the dataset.

{
  "dataVersion": {
    "version": "1"
  }
}

Additional request parameters

Non-agricultural areas

By default, responses exclude non-agricultural areas. To include background terrain such as forests or urban regions, set "includeNonAgriculturalAreas": true.

Capture date

The captureDate parameter filters landscape data to features observed on a specific date. For details, see the Retrieve historical captures example.

{
  "captureDate": {
    "year": 2023,
    "month": 10,
    "day": 15
  }
}

Next steps