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](https://developers.google.com/agricultural-understanding/api/request-format#targeting_with_coordinates) or an
[S2 cell ID](https://developers.google.com/agricultural-understanding/api/request-format#targeting_with_s2_cells).

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

> [!NOTE]
> **Note:** The following parameters are only supported in the `lookupLandscape` endpoint.

### 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](https://developers.google.com/agricultural-understanding/api/complete-examples/retrieve-historical-captures)
example.

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

> [!WARNING]
> **Warning:** Passing a specific `captureDate` limits the response to features extracted from imagery captured on a specific date. Features may be missing on a specific date due to cloud cover or other satellite imagery quality issues.

## Next steps

- Understand response data in [Response format](https://developers.google.com/agricultural-understanding/api/response-format).
- Explore endpoint details in the [REST API reference](https://developers.google.com/agricultural-understanding/reference/rest).