Set up the Geocoding API

European Economic Area (EEA) developers

If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.

This document describes the steps needed to start using the Geocoding API.

1. Account and billing Ensure that you meet the prerequisites.

2. Enable the API Enable the API in your Google Cloud project.

3. Make your first request Configure an API key to make an authenticated API request.

Google Maps Platform products are secured from unauthorized use by requiring API calls to include an API key.

Get an API key for use with Geocoding API

An API key is a unique alphanumeric string that associates your Cloud Billing account and Google Cloud project with the request your application makes to a Google Maps Platform API or SDK.

To add Geocoding API to an API key:

Console

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

   Go to the Keys & Credentials page

2. If prompted, select an existing project.

3. The list of available keys appears under API Keys.

   If you don't have an API key, or you want to create an API key for use with the Geocoding API, create a new API key:

   1. On the Keys & Credentials page, click + Create credentials > API key.

      The API key created dialog displays your newly created API key.

4. Click the Name of an API key to edit the key.

5. On the edit page, under Key restrictions:

   • Under Application restrictions, if any option other than None is selected, only requests originating from those sources are permitted. For more information, see Restrict your API keys.

   • Under API restrictions:

     • If Restrict key is selected, select the drop-down box to add the Geocoding API to the API key.
     • If Don't restrict key is selected, then you can use the API key to make requests to Geocoding API.

     Remember to restrict the API key before using it in production.

6. Select Save.
7. Select Show key for the key you edited to display the key's alphanumeric string. Pass that string to the example request shown in the next section.

gcloud

1. Get the ID of the key that you want to update.

   The ID is not the same as the display name or the key string. You can get the ID by using the following gcloud command to list the keys in your project.

   gcloud services api-keys list

   The ID is part of the name field of the response for each key:

   name: projects/PROJECT_ID/locations/global/keys/KEY_ID

2. If you don't have an API key, or you want to create an API key for use with the Geocoding API, create a new API key:

   gcloud services api-keys create \
       --project "PROJECT" \
       --display-name "DISPLAY_NAME"

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

   • gcloud services api-keys create

3. Use the gcloud services api-keys update command to specify which services an API key can be used to authenticate to.

   Replace the following values:

   • KEY_ID: The ID of the key that you want to restrict.

   • SERVICE_1, SERVICE_2...:

     The service names of the APIs that the key can be used to access. You must provide all service names with the update command; the service names provided replace any existing services on the key.

   You can find the service name by searching for the API on the API dashboard. For the Geocoding API, the service names geocoding-backend.googleapis.com.

   gcloud services api-keys update KEY_ID \
   --api-target=service=geocoding-backend.googleapis.com \
   --api-target=service=SERVICE_1 --api-target=service=SERVICE_2
   

Make an API request

Make a Geocoding API request to return an XML response for a query on the address "1600 Amphitheatre Parkway, Mountain View, CA". You must include your API key's alphanumeric string with every request and use HTTPS for requests that include the API key.

1. Click API_KEY in the code below to insert the key's alphanumeric string:

   curl 'https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY'
   

2. Click the copy icon in the code sample, , to copy the curl command.
3. Paste the command in a terminal window and run the command.

The response is an XML object in the form:

<?xml version="1.0" encoding="UTF-8"?>
<GeocodeResponse>
 <status>OK</status>
 <result>
  <type>street_address</type>
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
  <address_component>
   <long_name>1600</long_name>
   <short_name>1600</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Amphitheatre Parkway</long_name>
   <short_name>Amphitheatre Pkwy</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Mountain View</long_name>
   <short_name>Mountain View</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara County</long_name>
   <short_name>Santa Clara County</short_name>
   <type>administrative_area_level_2</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>California</long_name>
   <short_name>CA</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>United States</long_name>
   <short_name>US</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>94043</long_name>
   <short_name>94043</short_name>
   <type>postal_code</type>
  </address_component>
  ...
 </result>
</GeocodeResponse>

Apply API key restrictions

Caution: An unrestricted API key can be used to make a request to any Google Maps Platform service, including the Geocoding API. Google strongly recommends that you restrict your API keys by limiting their usage to only those APIs needed for your application. Restricting API keys adds security to your application by protecting it from unwarranted requests. For more information, see Restrict your API key.

Google strongly recommends that you restrict your API keys by limiting their usage to those only APIs needed for your application. Restricting API keys adds security to your application by protecting it from unwarranted requests. You are financially responsible for charges caused by abuse of unrestricted API keys. For more information, see Google Maps Platform security guidance.

API keys support two types of restrictions:

• API restrictions specify which SDKs and APIs can be called using the API key.
• Application restrictions specify which websites, IP addresses, or apps can use an API key.

For more information on applying restrictions, see Restrict your API keys.

What's next

Now that you have enabled Geocoding API and made a successful request, see Geocoding an address to learn more about using the API.