Hide
Google Places API

Place Add

By adding a place, you can supplement the data in the Google Maps database with data from your application. This allows you to:

  • Instantly update the data in Google's database for your users.
  • Submit new places to a moderation queue for addition to the Google places database.
  • Differentiate your application from other apps with similar functionality.
  • Create applications that are targeted to a specific user base or geographic location.
  • Influence the results of a Places Search issued from your application.
  1. Overview
  2. Add a place
  3. Delete a place
  4. Status codes
  5. Error messages
  6. The sensor parameter

Overview

When you add a place, the new place is available immediately in Nearby Searches initiated by your application. The new place also enters a moderation queue to be considered for Google Maps. A newly-added place does not appear in Text Search or Radar Search results, or to other applications, until it has been approved by the moderation process.

You can also delete places that have been added by your application, until they have been moderated. Once moderated and added into the Google database, a place can no longer be deleted. Places that are not accepted by the moderation process will continue to be visible to the application that submitted them.

Add a place

A place add request is an HTTP POST request similar to the example below:


JSON
POST https://maps.googleapis.com/maps/api/place/add/json?key=API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "location": {
    "lat": -33.8669710,
    "lng": 151.1958750
  },
  "accuracy": 50,
  "name": "Google Shoes!",
  "phone_number": "(02) 9374 4000",
  "address": "48 Pirrama Road, Pyrmont, NSW 2009, Australia",
  "types": ["shoe_store"],
  "website": "http://www.google.com.au/",
  "language": "en-AU"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/add/xml?key=API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceAddRequest>
  <location>
    <lat>-33.8669710</lat>
    <lng>151.1958750</lng>
  </location>
  <accuracy>50</accuracy>
  <name>Google Shoes!</name>
  <phone_number>(02) 9374 4000</phone_number>
  <address>48 Pirrama Road, Pyrmont, NSW 2009, Australia</address>
  <type>shoe_store</type>
  <website>http://www.google.com.au/</website>
  <language>en-AU</language>
</PlaceAddRequest>
      

Note that the URL path indicates the format of the input and output:

  • json (recommended) indicates input and output in JavaScript Object Notation (JSON).
  • xml indicates input and output as XML.

The URL must contain the following parameter:

  • key — Your application's API key. This key identifies your application for purposes of quota management and so that places added from your application are made immediately available to your application. Visit the Google Developers Console to create an API project and obtain your key.

The request body contains information about the place. It must be structured according to the specified output parameter (JSON or XML).

  • accuracy — The accuracy of the location signal on which this request is based, expressed in meters.
  • address (recommended, to improve chances of passing moderation) — The address of the place you wish to add. If a place has a well-formatted, human-readable address, it is more likely to pass the moderation process for inclusion in the Google Maps database.
  • language — The language in which the place's name is being reported. See the list of supported languages and their codes. Note that we often update supported languages so this list may not be exhaustive.
  • location (required) — The geographical location, specified as latitude and longitude values, of the place you want to add.
  • name (required) — The full text name of the place. Limited to 255 characters.
  • phone_number (recommended, to improve chances of passing moderation) — The phone number associated with the place. If a place has a well-formatted phone number, it is more likely to pass the moderation process for inclusion in the Google Maps database. This number should be in local or international format:
    • Local format may differ by country. See the Wikipedia article. For example, the local phone number for Google's Sydney, Australia office is (02) 9374 4000.
    • International format includes the country code, and is prefixed with a plus (+) sign. For example, the international phone number for Google's Sydney, Australia office is +61 2 9374 4000.
  • types (required) — The category in which this place belongs. While types takes an array, only one type can currently be specified for a place. XML requests require a single <type> element. See the list of supported types for more information. If none of the supported types are a match for this place, you may specify other.
  • website (recommended, to improve chances of passing moderation) — A URL pointing to the authoritative website for this Place, such as a business home page. If a Place has a well-formatted website address, it is more likely to pass the moderation process for inclusion in the Google Maps database.

Place add responses

Place add responses are returned in the format indicated by the output parameter in the request's URL path.

The API returns a status code, and if the request was successful the response includes the following properties for the new place:

  • place_id: A textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the placeid field of a Place Details request. For more information about place IDs, see the place ID overview.
  • scope: Indicates the scope of the place_id. The possible values for this field are:
    • APP: The place ID is recognized by your application only. Note: Place add responses will always have a scope of APP, because the place has not yet passed the moderation process.
    • GOOGLE: The place ID is available to other applications and on Google Maps. As noted above, place add responses will never have a Google-wide scope.
  • reference: A unique token that you can use to retrieve additional information about this place. Note: The reference is deprecated in favor of place_id. See the deprecation notice on this page.
  • id: A unique stable identifier denoting this place. This identifier cannot be used to retrieve information about this place, but is guaranteed to be valid across sessions. It can be used to consolidate data about this place, and to verify the identity of a place across separate searches. Note: The id is deprecated in favor of place_id. See the deprecation notice on this page.
{
  "status": "OK",
  "place_id": "CdIJN2t_tDeuEmsRUsoyG83frY4",
  "scope": "APP",
  "reference": "CiQgAAAAeTQS1RtzAyVRVjHcRiIWmWeqcAl3k7bluW7GINLDULESEHozTQhy6OHJw03ziDvY1uEaFAP_vDRhK-UbWw3Gd7Ulqm3eRjIs",
  "id": "6947fc4007436a71dbda51ef9a58627c8e8858f9"
}

Delete a place

A place can only be deleted if:

  • The place was added by the application that is requesting the deletion.
  • The place add request has not successfully passed through the Google Maps moderation process, and the place is therefore visible only to the application that added it.

If you try to delete a place that does not meet these criteria, the API will return a REQUEST_DENIED status code.

A place delete request is an HTTP POST request of the following form:


JSON
POST https://maps.googleapis.com/maps/api/place/delete/json?key=API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "place_id": "place ID"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/delete/xml?key=API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceDeleteRequest>
  <place_id>place ID</place_id>
</PlaceDeleteRequest>
      

Note that the URL path indicates the format of input and output:

  • json (recommended) indicates input and output in JavaScript Object Notation (JSON)
  • xml indicates input and output as XML

The URL must contain the following parameter:

  • key — Your application's API key. This key identifies your application for purposes of quota management and so that places added from your application are made immediately available to your application. Visit the Google Developers Console to create an API project and obtain your key.

The request body must be structured according to the specified output parameter (JSON or XML). It must include one of the following two fields:

  • place_id: A string identifying the place that must be deleted, returned from a place search. For more information about place IDs, see the place ID overview.
  • Alternatively, you can specify a reference to identify the place. Note that the reference is deprecated in favor of place_id. See the deprecation notice on this page.

Place delete responses

Place delete responses are returned in the format indicated by the output parameter in the request's URL path.

A successful delete request returns the following status code:

{
  "status": "OK"
}

Status codes

Status codes for place add/delete requests are:

  • OK indicates that no errors occurred; the place was successfully added or deleted.
  • UNKNOWN_ERROR indicates a server-side error; trying again may be successful.
  • OVER_QUERY_LIMIT indicates that you are over your quota.
  • REQUEST_DENIED indicates that your request was denied. This could be caused by attempting to delete a place that was added by another application, or that has gone through the Google Maps moderation process.
  • INVALID_REQUEST generally indicates that the request contains missing parameters. It will also be returned when attempting to add a place whose name is greater than 255 characters.
  • NOT_FOUND can be returned for place delete requests, and indicates that the passed reference could not be resolved to a place.

Error messages

When the Places service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about the reasons behind the given status code.

The sensor parameter

The Google Places API previously required that you include the sensor parameter to indicate whether your application used a sensor to determine the user's location. This parameter is no longer required.