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 with billing enabled. Use this guided setup flow to create a project and enable the necessary services. You need a Cloud project with billing to create API keys.

2. Request API access since the API requires allowlisting. Provide the following information to the Google team:

   • Google Workspace Customer ID (GWCID). See Find your customer ID for instructions on how to find it.
   • The email address of the person who will enable the API for your Google Cloud project.

3. Wait for the Google team to add your email and GWCID to the API allowlist. You can enable the API after you receive confirmation.

Enable the API and create an API key

Once you get access to the API, you can enable the API and create a 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.