Nearby API

NNearby Places API, enables you to add discovery and search of nearby POIs by searching for a generic keyword used to describe a category of places or via the unique code assigned to that category.


Security Type:

This APIs follow OAuth2 based security. To know more on how to create your authorization tokens, please use our authorization token URL. More details available here



Request Parameters
a. Mandatory Parameters:
  1. keywords (string) e.g. FODCOF, Shoes, Coffee, Versace, Gucci, H&M, Adidas, Starbucks, B130 {POI, House Number, keyword, tag}
  2. refLocation {string (latitude[double],longitude[double])}: Provides the location around which the search will be performed. e.g. refLocation=28.454,77.435
b. Optional Parameters:
  1. page (integer): provides number of the page to provide results from.
  2. sort (string): provides configured sorting operations for the client on cloud. Below are the available sorts:
    a) dist:asc & dist:desc - will sort data in order of distance from the passed location (default).
    b) name:asc & name:desc - will sort the data on alphabetically bases.
  3. radius (integer): provides the range of distance to search over (default: 1000, min: 500, max: 10000).
  4. bounds (x1,y1;x2,y2): Allows the developer to send in map bounds to provide a nearby search of the geobounds. where x1,y1 are the lat lng of.
  5. region (string): it takes in the country code. LKA, IND, BTN, BGD, NPL for Sri-Lanka, India, Bhutan, Bangladesh, Nepal respectively. Default is India (IND)

To send multiple keywords in a request, we’ve defined a couple of operators that can help the developers wrap their applications around this functionality. Below are the operators:

  1. The “ ; ” Operator: This operator is an “or” operator. Defining multiple keywords separated with a “ ; ” would provide results that satisfies either of the keywords.
  2. The “ $ ” Operator: This operator is a “and” operator. Defining multiple keywords separated with a “ $ ” would provide results that satisfy all the provided keywords. (default).

To use these operators, simple just send in the keywords parameter like below:
&keywords=coffee ; tea $ sea food ; alcohol

The above nearby search would yield in results that either provide coffee or tea but must provide either sea food or alcohol.

Please Note: the spacing in the above example is of no relevance to the search result. It’s just there to provide better understanding.

Request Headers

The Atlas API leverages OAuth 2.0 based security. Hence, the developer would need to send a request for access token using their client_id and client_secret to the OAuth API. Once validated from the OAuth API, the access_token and the token_type need to be sent as Authorization header with the value: “{token_type} {access_token}”.

1. Authorization: “{token_type} {access_token}”.
Response Type


Response Codes {as HTTP response code}
  1. 200: To denote a successful API call.
  2. 204: To denote the API was a success but no results we’re found.
Client-Side Issues:
  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer’s key is not allowed to send a request.
  3. 403: Forbidden, Developer’s key has hit its daily/hourly limit.
Server-Side Issues:
  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success.
  2. 204: No matches we’re found for the provided query.
  3. 400: Something’s just not right with the request.
  4. 401: Access Denied.
  5. 403: Services for this key has been suspended due to daily/hourly transactions limit.
  6. 500: Something went wrong.
  7. 503: Maintenance Break.
Response Parameters

The response data parameters and objects are as below:
For the suggested Locations object: (data type: [ object ])

  1. distance (integer): provides the distance from the provided location bias in meters.
  2. eLoc (string): Place Id of the location 6-char alphanumeric.
  3. email (string): Email for contact.
  4. entryLatitude (double): latitude of the entrance of the location.
  5. entryLongitude (double): longitude of the entrance of the location.
  6. keywords ( [ string ] ): provides an array of matched keywords or codes.
  7. landlineNo (string): Email for contact.
  8. latitude (double): Latitude of the location.
  9. longitude (double): longitude of the location.
  10. mobileNo : Phone number for contact.
  11. orderIndex (integer): the order where this result should be placed
  12. placeAddress (string): Address of the location.
  13. placeName (string): Name of the location.
  14. type (string): Type of location POI or Country or City.
Input Request Sample;beer&refLocation=28.631460,77.217423

Output Response Sampl
{  "suggestedLocations": [  {  "distance": 91,  "eLoc": "K8U77U",  "email": "",  "entryLatitude": 28.631989,  "entryLongitude": 77.217886,  "keywords": [  "FODCOF",  "759"  ],  "landlineNo": "+911141562923",  "latitude": 28.632215,  "longitude": 77.217792,  "mobileNo": "",  "orderIndex": 1,  "placeAddress": "Block A, Hamilton House, Inner Circle, Connaught Place",  "placeName": "Starbucks",  "type": "POI"  },  {  "distance": 101,  "eLoc": "AC852C",  "email": "",  "entryLatitude": 28.631843,  "entryLongitude": 77.216586,  "keywords": [  "FODCOF"  ],  "landlineNo": "+911123363652, +911123363074, +911123363074",  "latitude": 28.631803,  "longitude": 77.2164560000001,  "mobileNo": "",  "orderIndex": 2,  "placeAddress": "P 5/90 , Connaught Place, Connaught Circus",  "placeName": "Madras Coffee House",  "type": "POI"  }  ]  }