Google Places API

Place Actions

Place actions are not included in the Places Library of the Google Maps JavaScript API v3.

Place actions allow you to supplement the data in Google's places database with data from your application. Data added using place actions is application specific, and will be available to applications that share the same API key. With place actions you can add and remove places, schedule events, and allow users to bump the priority ranking of a location or event.

Supplementing Google's data with your own allows you to:

  • Differentiate your application from other apps with similar functionality.
  • Instantly update the data in Google's database for your users.
  • 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. Adding and Deleting Places
    1. Adding Places
    2. Deleting Places
  2. Events
    1. Adding Events
    2. Deleting Events
    3. Event Details
  3. Place Bumps
    1. Place Bump Requests
    2. Event Bump Requests
    3. Bump Responses
  4. Error Messages

Adding and Deleting Places

Place action requests are used to add new places or delete existing ones. New places will be available immediately in place nearby searches initiated by your application, and will enter the moderation queue to be considered for Google Maps. A newly-added place will not appear in place text search or radar search results, or to other applications, until it has been approved by the moderation process.

Places that have been added by your application can also be deleted, until they have been moderated. Once moderated and added into the full place search results, 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.

Adding Places

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?sensor=true_or_false&key=AddYourOwnKeyHere HTTP/1.1
Host: maps.googleapis.com

{
  "location": {
    "lat": -33.8669710,
    "lng": 151.1958750
  },
  "accuracy": 50,
  "name": "Google Shoes!",
  "types": ["shoe_store"],
  "language": "en-AU"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/add/xml?sensor=true_or_false&key=AddYourOwnKeyHere 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>
  <type>shoe_store</type>
  <language>en-AU</language>
</PlaceAddRequest>
      

Note that the POST URL's 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 POST URL must contain the following parameters:

  • sensor — Indicates whether or not the place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request. This value must be either true or false.
  • 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 app. Visit the APIs Console to create an API project and obtain your key.

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

  • location (required) — The textual latitude/longitude value from which you wish to add new place information.
  • name (required) — The full text name of the place. Limited to 255 characters.
  • 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.
  • accuracy — The accuracy of the location signal on which this request is based, expressed in meters.
  • 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.

Place Add Responses

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

An add request returns a status code, the new place's reference, and its id:

{
  "status": "OK",
  "reference": "CiQgAAAAeTQS1RtzAyVRVjHcRiIWmWeqcAl3k7bluW7GINLDULESEHozTQhy6OHJw03ziDvY1uEaFAP_vDRhK-UbWw3Gd7Ulqm3eRjIs",
  "id": "6947fc4007436a71dbda51ef9a58627c8e8858f9"
}

Deleting Places

A place can only be deleted if:

  • It was added by the same application as is requesting its deletion.
  • It has not successfully passed through the Google Maps moderation process, and and is therefore not visible to all applications.

Attempting to delete a place that does not meet these criteria 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?sensor=true_or_false&key=AddYourOwnKeyHere HTTP/1.1
Host: maps.googleapis.com

{
  "reference": "place_reference"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/delete/xml?sensor=true_or_false&key=AddYourOwnKeyHere HTTP/1.1
Host: maps.googleapis.com

<PlaceDeleteRequest>
  <reference>place_reference</reference>
</PlaceDeleteRequest>
      

Note that the POST URL's 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 POST URL must contain the following parameters:

  • sensor — Indicates whether the place request came from a device using a location sensor (e.g. a GPS). This value must be either true or false.
  • 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 app. Visit the APIs Console to create an API project and obtain your key.

The POST body contains the place's reference. The body should be structured according to the specified output (JSON or XML). The single, required field is:

  • reference — The textual identifier that uniquely identifies this place, returned from a place search.

Place Delete Responses

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

A delete request will return a status code:

{
  "status": "OK"
}

Status Codes

Status codes for place action 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 due to a lack of a sensor parameter, or 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.

Events

The Google Places API includes support for events, which are defined as any type of public or private gathering, performance, or promotion that occurs at a location listed in the Places service.

The events service is intended to provide notice and information about events that are happening currently, so that users can find or bump them. Events are included in place search results as soon as they are added, and expire after their set duration has elapsed. Results will include events added by your application.

Adding Events

Events can be attached to any place that is returned in place search results, including places that are only available to your application.

Events begin appearing in place search and details results as soon as they're added. Events will expire from results once their duration has passed, but will continue to be accessible to event details searches. Note that events added by your application are only visible to your application.

Event Add Requests

An event add request is an HTTP POST request of the following form:

POST https://maps.googleapis.com/maps/api/place/event/add/format?sensor=true_or_false&key=api_key

{
  "duration" : 172800,
  "language" : "EN-CA",
  "reference" : "CnRkAAAAGnBVNFDeQoOQHzgdOpOqJNV7K9-etc",
  "summary" : "Rock n Roll Dreams: The band fully electric in my kitchen and drinking all my beer.",
  "url" : "http://www.example.com/event_details/10476.html"
}

where format may be either of the following values:

  • json (recommended) indicates that you are passing JavaScript Object Notation (JSON), and that JSON will be returned.
  • xml indicates input/output as XML.

The POST URL must contain valid key and sensor values:

  • key: Your application's API key. This key identifies your application for purposes of quota management and so that events added from your application are made immediately available to your app. Visit the APIs Console to create an API project and obtain your key.
  • sensor: Indicates whether or not the request came from a device using a location sensor (e.g. a GPS). This value must be either true or false.

The POST body must contain the following required parameters:

  • duration: The duration of the event, in seconds. The event's start time is considered to be the time at which it was added. Once the duration has elapsed, the event is removed from the search results (though it is still accessible with a details search).
  • reference: The reference value of the place where the event is happening.
  • summary: A textual description of the event. This property accepts a string (up to 255 characters), the contents of which are not sanitized by the server. Your application should be prepared to prevent or deal with attempted exploits, if necessary.

Optional parameters in the POST body are:

  • language: The language in which the event is being reported, specified as a CLDR language identifier.
  • url: A URL pointing to details about the event.

Event Add Responses

An event add response takes the following form:

{
  status: ‘OK’,
  event_id: 'weafgerg1234235'
}

A successful add request will return a unique event_id value, identifying this event. It can be used in conjunction with the reference of the place to which the event is attached, to return the event details or to delete the event.

Possible status values are:

  • OK: Add was successful.
  • INVALID_REQUEST: Can be caused by an incorrect or missing reference value, a missing summary, or a missing duration.
  • NOT_FOUND The referenced location was not found in the places database.
  • REQUEST_DENIED: Indicates either a missing or incorrect key value, or use of http instead of https.
  • UNKNOWN_ERROR: The service encountered an unknown error; try again shortly.

Event Deletions

Event Delete Requests

Events that have been added using your API key can also be deleted with a POST request containing the same key. Deleting an event completely removes it from the Places service and can not be undone.

An event delete request is an HTTP POST request of the following form:

POST https://maps.googleapis.com/maps/api/place/event/delete/format?sensor=true_or_false&key=api_key

{
  reference: 'CnRkAAAAGnBVNFDeQoOQHzgdOpOqJNV7K9-etc',
  event_id: 'weafgerg1234235'
}

where format may be either of the following values:

  • json indicates that you are passing JavaScript Object Notation (JSON), and that JSON will be returned.
  • xml indicates input/output as XML.

The POST URL must contain valid key and sensor values:

  • key: Your application's API key. This key identifies your application for purposes of quota management and so that events added from your application are made immediately available to your app. Visit the APIs Console to create an API project and obtain your key.
  • sensor: Indicates whether or not the request came from a device using a location sensor (e.g. a GPS). This value must be either true or false.

The POST body must contain the following required parameters:

  • event_id: The unique event_id for this event.
  • reference: The reference value of the Place to which the event is attached.

Event Delete Responses

An event delete response contains a status value for this request:

{
  status: ‘OK’,
}

Possible status values are:

  • INVALID_REQUEST
  • NOT_FOUND
  • OK
  • REQUEST_DENIED
  • UNKNOWN_ERROR

Event Details

When an event is returned as part of a place search or details result, its unique event_id is included. That property can later be used to query the EventService for the event details, even after the event has expired from the search results.

Event Details Requests

An event details request is an HTTP request of the following form:

https://maps.googleapis.com/maps/api/place/event/details/format?sensor=true_or_false
  &key=api_key
  &reference=CnRkAAAAGnBVNFDeQoOQHzgdOpOqJNV7K9-etc
  &event_id=weafgerg1234235

where format may be either of the following values:

  • json (recommended) indicates that JavaScript Object Notation (JSON) will be returned.
  • xml indicates output as XML.

The following URL parameters are required:

  • reference: The reference value of the place to which the event is attached.
  • event_id: The event's unique event_id.

Event Details Responses

A successful event details request returns the following response body:

{
  "result" : {
    "duration" : 172800,
    "event_id" : "7lH_gK1GphU",
    "start_time" : 1293840000,
    "summary" : "Rock n Roll Dreams: The band fully electric in my kitchen and drinking all my beer.",
    "url" : "http://www.example.com/event_details/10476.html"
  },
  "status" : "OK"
}

The response includes a result property and a status property.

The result property contains:

  • duration: The duration of the event in seconds.
  • event_id: The unique ID of this event.
  • start_time: Expressed in Unix time.
  • summary: A textual description of the event. This property contains a string, the contents of which are not sanitized by the server. Your application should be prepared to prevent or deal with attempted exploits, if necessary.
  • url: A URL pointing to details about the event. This property will not be returned if no URL was specified for the event.

Possible status values are:

  • INVALID_REQUEST generally indicates that the reference is missing.
  • NOT_FOUND means that an event could not be found with the specified event_id.
  • OK indicates that no errors occurred.
  • REQUEST_DENIED indicates that your request was denied, generally because of lack of a sensor parameter or an incorrect API key.
  • UNKNOWN_ERROR generally indicates a server-side error; trying again may be successful.

Place Bumps

Earlier versions of the Places API referred to a bump as a check-in.

You can use the Places API to bump up the ranking of individual places or Events within your application. Bumps from your application are reflected in place search results for your app — popular establishments are ranked more highly, making it easy for your users to find likely matches. As bump activity changes over time, so will the ranking of each place.

Before you can bump a place, you will first have to have a reference from a place search request.

Requesting a Bump

A bump is an HTTP POST request of the following form:


JSON
POST https://maps.googleapis.com/maps/api/place/bump/json?sensor=true_or_false&key=AddYourOwnKeyHere HTTP/1.1
Host: maps.googleapis.com

{
  "reference": "place_reference"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/bump/xml?sensor=true_or_false&key=AddYourOwnKeyHere HTTP/1.1
Host: maps.googleapis.com

<BumpRequest>
  <reference>place_reference</reference>
</BumpRequest>
      

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

  • json (recommended) indicates that you are passing JavaScript Object Notation (JSON), and that JSON will be returned.
  • xml indicates input/output as XML.

The POST URL must contain the following parameters:

  • sensor — Indicates whether the bump came from a device using a location sensor (e.g. a GPS). This value must be either true or false.
  • key — Your application's API key. This key identifies your application for purposes of quota management, and to apply bump data from your application to the ranking of Places in your search results.

The POST body may contain the following fields:

  • reference — (Required) A textual identifier that uniquely identifies a place, returned from a place search.
  • event_id— (Optional) The unique event_id for this event.

Bumping an Event

Once you have an event_id and a place reference, you can bump an event. An event bump use the same API endpoint as a place bump.

An event bump request takes the same parameters as a place bump, along with an additional event_id parameter. An event bump is an HTTP POST request of the following form:

POST https://maps.googleapis.com/maps/api/place/bump/format?sensor=true_or_false&key=api_key

{
  place_reference: 'CnRkAAAAGnBVNFDeQoOQHzgdOpOqJNV7K9-etc',
  event_id: 'weafgerg1234235',
}

Bump Responses

The status field within the response object contains the status of the request, and may contain debugging information to help you track down why the a request failed:

  • OK indicates that no errors occurred. The bump was successful.
  • 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, generally because of lack of a sensor parameter.
  • INVALID_REQUEST generally indicates that the request contains missing parameters.
  • NOT_FOUND indicates that the referenced location was not found in the places database.

The following example reports a successful bump:

POST https://maps.googleapis.com/maps/api/place/bump/json?sensor=true&key=AddYourOwnKeyHere HTTP/1.1
Host: maps.googleapis.com

{
  "reference": "CmRRAAAATpOheNdDJDp5cdz1EGLqiGWhdrUnsyvn5plkWb6IbydAdnExNaDAdXBxRjhaFINDJU1UvLkVU5ZTFmUDsIDRrUCm-9Q7XLu6vi-bspAju4GG2XzRhv9ZBy9yJbK2PJVOEhD3QlprissY-rI0w3Ego93jGhSy7x8zDUYSrovufH1OxUGkcbjHBg"
}

It returns the following JSON response:

{
  "status": "OK"
}

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.