Generate a new video

The renderVideo method requests the generation of an aerial view video for the specified US postal address. If the video already exists for the specified address, then this method returns metadata about the video.

How to use the API

Generate a new aerial video by making an HTTPS POST request to the renderVideo endpoint, passing your API Key and a US postal address, as shown in the following example. The rendering process can take anywhere from an hour to a few hours.

curl -X POST -d '{
  "address": "POSTAL_ADDRESS"
}' \
-H 'Content-Type: application/json' \
"https://aerialview.googleapis.com/v1/videos:renderVideo?key=YOUR_API_KEY"

Example request

The following code example requests the generation of an aerial view video for 500 W 2nd St, Austin, TX, 78701.

curl -X POST -d '{
  "address": "500 W 2nd St, Austin, TX 78701"
}' \
-H 'Content-Type: application/json' \
"https://aerialview.googleapis.com/v1/videos:renderVideo?key=YOUR_API_KEY"

Example response

The following JSON code samples show the possible responses to the example video request.

Invalid address response

The address is either incorrect, or it isn't within the United States.

{
  "error": {
    "code": 400,
    "message": "Address not supported.",
    "status": "INVALID_ARGUMENT"
  }
}

Processing response

The Aerial View API is now rendering your video. The response contains the videoId, which you can use to retrieve the video.

{
  "state": "PROCESSING",
  "metadata": {
    "videoId": "x89iJAJi1wzs7DIAFQF7Va"
  }
}

The rendering process can take anywhere from an hour to a few hours. If the video is still processing, you can use lookupVideo to poll the video status until it returns a state of ACTIVE.

To poll, make a request to lookupVideo, passing the videoId. Rendering can take several hours, so use exponential backoff to space out your calls.

Active response

When renderVideo returns a state value of ACTIVE, it means the video has finished rendering, and you can retrieve it by calling lookupVideo with the videoId.

{
  "state": "ACTIVE",
  "metadata": {
    "videoId": "x89iJAJi1wzs7DIAFQF7Va"
  }
}