How to use the Aerial View API

  • The Aerial View API offers two workflows: one for retrieving existing videos and another for generating new ones.

  • To determine if a video exists for a location, utilize the lookupVideoMetadata function.

  • If a video doesn't exist, initiate video generation using the renderVideo function and monitor its status with lookupVideoMetadata until it becomes active.

  • Once the video is active, retrieve its URLs via the lookupVideo function for access and use.

  • Aerial View API video IDs can be stored for future use, unlike other Google Maps Platform content.

The Aerial View API supports two general workflows. Your approach depends on whether the video you're requesting exists or not. If you're unsure whether the video exists, you should use lookupVideoMetadata to determine the video's state.

Workflow to generate or retrieve videos

Use the following workflow to generate or retrieve an aerial view video:

  1. Check if Google has already generated a video for the location using lookupVideoMetadata.
  2. If no video exists (lookupVideoMetadata returned a 404), call renderVideo to generate a new video.
    1. Call lookupVideoMetadata using the videoId or address to poll the endpoint until the video's state is ACTIVE. Rendering can take several hours, so use exponential backoff to space out your calls.

  3. If the video is active (lookupVideoMetadata returned a state of ACTIVE), call lookupVideo to fetch the video's URIs.

This workflow is represented in the diagram below:

Chart displaying the workflow outlined above

Save video IDs for later use

Subject to the Service Specific Terms for Aerial View API, Aerial View API video IDs are exempt from the caching restrictions stated in Section 3.2.3(b)(No Caching) of the Google Maps Platform Terms of Service. You can therefore store video ID values for later use.