The Maps Embed API quickstart

Page Summary

• Embed interactive Google Maps or Street View panoramas on your webpage with simple HTTP requests, without needing JavaScript.

• The Maps Embed API is free to use with unlimited requests, but requires a valid Google Cloud API key and a billing account (though no charges will be incurred for typical usage).

• To get started, you'll need to enable the Maps Embed API, create an API key within your Google Cloud project, and generate an iframe with your desired location and key.

• You can test the embedded map by creating a simple HTML file containing the generated iframe and opening it in a web browser.

Place an interactive map or Street View panorama on your web page with an HTTP request—no custom JavaScript required.

Costs

All Maps Embed API requests are available at no charge with unlimited usage. However, all requests still require a valid Google Cloud API key. For more information, see Usage and Billing.

Before you begin

To create an embedded map on your web page, complete the following required setup steps:

Step 1: Set up your project

Console

1. In the Google Cloud console, on the project selector page, click Create Project to begin creating a new Cloud project.

   Go to the project selector page

2. Make sure that billing is enabled for your Cloud project. Confirm that billing is enabled for your project.

   Note: While you must set up a billing account to set up a Cloud project, actual usage of the Embed API is available at no charge.

   Google Cloud offers a $0.00 charge trial. The trial expires at the end of 90 days or after the account has accrued $300 worth of charges, whichever comes first. Cancel anytime. For more information, see Billing account credits and Billing.

Cloud SDK

gcloud projects create "PROJECT"

Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

• gcloud projects create

Note: If you don't plan to keep the resources that you create in a learning exercise, create a project instead of selecting an existing project. After you finish the exercise, you can delete the project, removing all resources associated with the project.

Step 2: Enable APIs or SDKs

To use Google Maps Platform, you must enable the APIs or SDKs you plan to use with your project.

Console

Enable the Maps Embed API

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-embed-backend.googleapis.com"

Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

• gcloud services enable
• gcloud services disable

Step 3: Get an API key

This step only goes through the API key creation process. If you use your API key in production, we strongly recommend that you restrict your API key. You can find more information in the product-specific Using API Keys page.

The API key is a unique identifier that authenticates requests associated with your project for usage and billing purposes. You must have at least one API key associated with your project. To create a new key or add an API or SDK to an existing key, follow these instructions.

Console

1. Go to the Google Maps Platform > Keys & Credentials page.

   Go to the Keys & Credentials page

2. If prompted, select your project.

3. Do one of the following:

   • Create a new key:

     1. Click Create credentials > API key.
     2. In the Create API key panel, open the Select API restrictions list.
     3. Clear any APIs that this key doesn't need, and make sure Maps Embed API stays selected.
     4. Click Create. The panel displays your new API key.

   • Use an existing key:

     1. Click the name of the key.
     2. In the Select API restrictions list, select Maps Embed API.
     3. Click Save.

   Selecting an API here doesn't enable it. Make sure Maps Embed API is enabled on its API Library page.

4. To see the key string later, go to the Keys & Credentials page and click Show key for the key.

If the console looks different from these steps, see Create an API key and Add API restrictions in the Google Cloud documentation.

Cloud SDK

Replace PROJECT_ID with your project ID in the following commands.

• Create a new key: Run the following command, and replace DISPLAY_NAME with a name for the key.

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=maps-embed-backend.googleapis.com

  Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

  • gcloud services api-keys create

• Use an existing key: Run the following command, and replace KEY_ID with the ID of the key. The --append flag keeps the APIs that the key already allows. Without it, the command replaces them.

  gcloud services api-keys update KEY_ID \
      --project="PROJECT_ID" \
      --append \
      --api-target=service=maps-embed-backend.googleapis.com

  Read more about the Google Cloud SDK, Cloud SDK installation, and the following commands:

  • gcloud services api-keys update
  • gcloud services api-keys list

  The key ID isn't the key string or display name. To find it, run gcloud services api-keys list --project="PROJECT_ID". The ID is the last part of the name field: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

To see the key string, run gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Generating an iframe

Click through the following options and add a location and API key to generate an iframe for your webpage. For additional parameters and options, see Embedding a map.

Testing your iframe

To see your iframe in an HTML browser window:

1. Open your default text editor. You should have text editors such as TextEdit or Microsoft Windows Notepad installed on your device by default.
2. Create an HTML file and name it index.html.

3. Add the following code with the iframe you generated above:

   <html>
     <!-- Replace this code comment with your iframe. -->
   </html>
   

4. Save your index.html HTML file.

5. Load the HTML file in a web browser by dragging it from your desktop onto your browser; alternatively, double-clicking the file works on most operating systems.

Congratulations! You just set up and built a map using the Maps Embed API.

Cleaning up

You can delete your Google Cloud project to stop billing for all the resources used within that project.

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you may have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

1. In the Google Cloud console, go to the Manage resources page:

   Go to the Manage resources page

2. If the project that you plan to delete is attached to an organization, select and expand the organization list at the top of the page.
3. In the project list, select the project that you want to delete and click Delete.
4. In the dialog, type the project ID and click Shut down to delete the project.

Next steps

• Start developing with the Maps Embed API by setting up your Google Cloud project:

  Set up in Cloud console

• For a list of additional parameters and options you can add in your iframe:

  Embedding a map

• Extend your Maps project with the JavaScript API:

  Maps JavaScript API