Set your default language: PHP | Curl

GET places/search

Used to perform a search against our database of global places. While no search parameters are required, a search without any parameters is likely to be meaningless. It's highly recommended to include GPS coordinates at a minimum.


Requires Authentication No
Rate Limited Yes
Response Formats json


Parameter Required Notes
key The application ID for the application making the request.
access_token Access token of authenticated user peforming the search. If included, additional meta information about the relationship of the user to the place is included).
lat Latitude of a given location to search for loacations near. Only decimal degrees are accepted latitude values (i.e. 32.78411)
lon Longitude of a given location to search for loacations near. Only decimal degrees are accepted longitude values (i.e. -79.93823)
count The total number of results to return.

Default is 20. Maximum is 50.
name Search for a specific place. Will match any part of a place name against the value given.
category Explore places by category. Common categories include 'shopping', 'bars', 'food', 'coffee' among others. When combined with the 'name' parameter, we will only search in the given category for the place name.

Additionally you may send one of our defined category id's for a more precise search. See our category documentation for more information about getting an appropriate category id.
max_distance The maximum distance from the given lat / lon. Note: The distance is an approximation of the distance and is fairly accurate for short distances. Accuracy is less precise over large distances (> 100 miles) and near the poles.

Default value is 1 mile or 1 km depending on the value provided in 'distance_units'
distance_units Determines the units of distance returned in results as well as the unit of distance represented by the 'max_distance' parameter.

Valid values are 'english' or 'metric'.

Default value is 'english'.


There are no unique error states for this endpoint, please see our page detailing general errors you may encounter.

Example Usage

  // Note: PHP Examples use the Heello PHP Client library
  require_once dirname(dirname(dirname(__FILE__))) . '/Heello.php';

  // You can get an Application Key and Secret by visiting:
  $api_application_key = "APPLICATION_KEY";
  $api_application_secret = "APPLICATION_SECRET";

  // You can get an access token and refresh token by implementing the auth
  // flow described at (or use the demo provided):
  $access_token = "ACCESS_TOKEN";

  $api = new Heello\Client($api_application_key, $api_application_secret);

    // Array of notifications for the auth'd user
    $places = $api->places->search(array(
      "count" => 4,
      "name" => "Starbucks",
      "lat" => 32.78411,
      "lon" => -79.93823

  catch (Exception $e){
    print $e->getMessage();
Please use the "Live Demo" below to see an example response.
You may need to login or create an account before making requests against the API.

Live Demo

Please login and create an application to perform live API testing.