Get Nearest Places Details
Contents
Mobile_API »Get Nearest Places
Base URL
https://apimobile.callproof.com
Endpoint
/api/places
Purpose
Searches for nearby places around a location (latitude/longitude, address, and/or ZIP code). Results can be filtered by keyword and category, support Google Places page tokens for additional results, and include distance from the user’s current location.
HTTP Method
POST
Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer access token |
Security
- Yes – Requires Bearer Token authentication.
Parameters
Path Parameters
None.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number used when building next-page navigation URLs |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| latitude | number/string | No | Search latitude. Used with longitude, or derived from address/ZIP when provided |
| longitude | number/string | No | Search longitude. Used with latitude, or derived from address/ZIP when provided |
| address | string | No | Address used to resolve latitude/longitude for the search |
| zip_code | string | No | ZIP/postal code used when address is empty to resolve location |
| keyword | string | No | Free-text search keyword (for example, business name) |
| category_id | string/integer | No | Place category identifier used to filter by business type |
| next_page_token | string | No | Token from a previous response to fetch the next set of places |
cURL Example for Android
curl --location 'https://apimobile.callproof.com/api/places?page=1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "latitude": "YOUR_LATITUDE", "longitude": "YOUR_LONGITUDE", "address": "", "zip_code": "", "keyword": "", "category_id": "", "next_page_token": "" }'
cURL Example for iOS
curl --location 'https://apimobile.callproof.com/api/places?page=1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "latitude": "YOUR_LATITUDE", "longitude": "YOUR_LONGITUDE", "address": "", "zip_code": "", "keyword": "", "category_id": "", "next_page_token": "" }'
Successful Response (200)
Returns a paginated list of nearby places.
| Field | Type | Description |
|---|---|---|
| clientStatusCode | integer | Status indicator for the client (for example, 200) |
| user_id | integer | Identifier of the authenticated user |
| company_id | integer | Identifier of the authenticated user’s company |
| data | array | List of place records (see below) |
| firstItemOnPage | integer | Index of the first item on the current page |
| lastItemOnPage | integer | Index of the last item on the current page |
| hasNextPage | boolean | Whether a next page is available |
| hasPreviousPage | boolean | Whether a previous page is available |
| isFirstPage | boolean | Whether the current page is the first page |
| isLastPage | boolean | Whether the current page is the last page |
| next_page_url | string/null | URL of the next page, when available |
| prev_page_url | string/null | URL of the previous page, when available |
| first_page_url | string | URL of the first page |
| last_page_url | string | URL of the last page |
| pageCount | integer | Total number of pages |
| pageNumber | integer | Current page number |
| pageSize | integer | Number of items per page (typically 20) |
| totalItemCount | integer | Total number of matching items |
| next_page_token | string | Token to request the next batch of places, when available |
| uri | string | Requested resource URI |
data[]
| Field | Type | Description |
|---|---|---|
| id | integer | Unique identifier of the place record |
| name | string | Place / business name |
| address | string | Street address |
| city | string | City |
| state | string | State abbreviation |
| zip | string | ZIP/postal code |
| phone_number | string | Formatted phone number, when available |
| latitude | string | Place latitude |
| longitude | string | Place longitude |
| distance | string | Distance from the user (for example, 1.25 M)
|
| record_color | string | Display color indicator for the place record |
| website | string | Website URL, when available |
| type | string | Place source type (for example, g for Google Places)
|
Error Responses
| Status Code | Meaning |
|---|---|
| 400 | Bad Request – places could not be retrieved |
| 401 | Unauthorized – missing, invalid, or expired Bearer token |
- 400 – Places lookup failed (for example, "Error while Retrieving Places" or "Error while retriving the places list").
- 401 – Authentication failed or the access token is missing/expired.
