The Agricultural Understanding API provides a REST interface through Google
Cloud API to retrieve data such as landscape features and crop predictions.

> [!NOTE]
> **Note:** The geographic components (like [S2 cells](https://s2geometry.io)) and underlying semantic representations of this data are defined in [Understanding
> the data](https://developers.google.com/agricultural-understanding/understanding-data). We assume you are comfortable with these concepts before integrating the REST API.

## Capabilities and limitations

**Capabilities:**

- **Spatial retrieval:** You can fetch agricultural features using coordinate points or level 13 S2 cell IDs.
- **Standardized format:** Landscape features and crop monitoring history are delivered as [GeoJSON (RFC
  7946)](https://datatracker.ietf.org/doc/html/rfc7946) `FeatureCollection` structures for integration into web apps, mobile dashboards, or GIS systems.

**Limitations:**

- **Vector output:** The API delivers vector features (boundaries, point coordinates, metadata) and does not provide raw satellite imagery.
- **No server-side aggregation:** The API returns features at the field level for specified regions and does not execute server-side spatial aggregations.
- **Grid boundary intersections:** Features are indexed by centroid location within level 13 S2 cells. Polygons near cell boundaries may extend beyond the cell perimeter.

<br />

## Core API endpoints

The Agricultural Understanding API exposes three primary endpoints across ALU
and AMED to support distinct real-world workflows.

**Agricultural Landscape Understanding (ALU)**:

- **`lookupLandscapeCaptureDate`** : Discovers the specific dates when satellite imagery was captured and processed for a given region. View the [`lookupLandscapeCaptureDate` reference
  documentation](https://developers.google.com/agricultural-understanding/reference/rest/v1/TopLevel/lookupLandscapeCaptureDate), then choose whether to specify a `captureDate` in your [API
  request](https://developers.google.com/agricultural-understanding/api/request-format#capture-date). To see an example query, see the [Retrieve historical
  captures](https://developers.google.com/agricultural-understanding/api/complete-examples/retrieve-historical-captures) page.
- **`lookupLandscape`** : Retrieves spatial feature boundaries and polygons for agricultural elements like fields, ponds, and trees. View the [`lookupLandscape` reference documentation](https://developers.google.com/agricultural-understanding/reference/rest/v1/TopLevel/lookupLandscape) or see an example query on the [Basic
  retrieval](https://developers.google.com/agricultural-understanding/api/complete-examples/basic-retrieval#lookuplandscape-example) page.

**Agricultural Monitoring and Event Detection (AMED)**:

- **`monitorLandscape`** : Fetches in-season and historical crop predictions and confidence scores for specified fields and time ranges. View the [`monitorLandscape` reference documentation](https://developers.google.com/agricultural-understanding/reference/rest/v1/TopLevel/monitorLandscape) or see an example query on the [Basic
  retrieval](https://developers.google.com/agricultural-understanding/api/complete-examples/basic-retrieval#monitorlandscape-example) page.

## Setup

Before you begin with the API, follow these steps:

1. Set up a Google Cloud project. Use this [guided setup
   flow](https://cloud.google.com/docs/enterprise/cloud-setup) to create a
   project, which you will use to call Agricultural Understanding APIs.

2. Request API quota. Because the API requires allowlisting, submit an
   allowlisting request using the [allowlisting request
   form](https://docs.google.com/forms/d/e/1FAIpQLSeZBFET3hFTGoparN24MRJQsfzmLRHYR7quoX_cLKaYnczqJA/viewform).

3. Wait for email confirmation. You will receive an email confirmation once
   your project quota has been provisioned or if further details are required.

> [!NOTE]
> **Note:** Allowlisting applies on a per-project basis. If you create a new project, submit the allowlisting request form with your new project number to request quota for that project.

### Enable the API and create an API key

Once your project is on the allowlist for API quota, you can enable the API and
create an API key:

1. Enable the API in your Google Cloud project by visiting [Agricultural
   Understanding
   API](https://console.cloud.google.com/apis/library/agriculturalunderstanding.googleapis.com)
   in the Google Cloud console.

2. Create an API key. See [Create an API
   key](https://cloud.google.com/docs/authentication/api-keys#create) in the
   Cloud documentation.

3. We recommend restricting the API key scope to only the Agricultural
   Understanding API. This prevents unauthorized use if the key is compromised.
   See [Restricting API
   keys](https://cloud.google.com/docs/authentication/api-keys#restricting_api_keys)
   in the Cloud documentation.

## Next steps

To use the API:

1. **Format your requests** : To provide coordinates and S2 cells in your request, see [API request
   format](https://developers.google.com/agricultural-understanding/api/request-format).
2. **Parse the output** : Get an overview of GeoJSON feature properties and response status codes in [Response
   format](https://developers.google.com/agricultural-understanding/api/response-format).
3. **Review REST API reference** : Explore all endpoints in the [REST API
   reference](https://developers.google.com/agricultural-understanding/reference/rest).
4. **Run complete examples** : Follow code samples in [Complete
   examples](https://developers.google.com/agricultural-understanding/api/complete-examples/basic-retrieval).