API overview

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

Note: The geographic components (like S2 cells) and underlying semantic representations of this data are defined in Understanding the 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) 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.

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, then choose whether to specify a captureDate in your API request. To see an example query, see the Retrieve historical captures page.
• lookupLandscape: Retrieves spatial feature boundaries and polygons for agricultural elements like fields, ponds, and trees. View the lookupLandscape reference documentation or see an example query on the Basic retrieval 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 or see an example query on the Basic retrieval page.

Setup

Before you begin with the API, follow these steps:

1. Set up a Google Cloud project. Use this guided setup flow 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.

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: 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 in the Google Cloud console.

2. Create an API key. See Create an API key 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 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.
2. Parse the output: Get an overview of GeoJSON feature properties and response status codes in Response format.
3. Review REST API reference: Explore all endpoints in the REST API reference.
4. Run complete examples: Follow code samples in Complete examples.