# Geolocation

> Seven operations on one route: geocode, reverse geocode, directions, distance matrix, text search, nearby search, and place details.

Source: https://docs.generalinput.com/api/platform/geolocation



<Endpoint method="POST" path="/v1/platform/geolocation" />

<Access scope="platform:use" />

One route, dispatched on the `operation` field. Responses use camelCase. Places operations use the Places API (New) and return Pro-tier fields.

## Pricing [#pricing]

| Operation         | Unit                                 | Price   |
| ----------------- | ------------------------------------ | ------- |
| `geocode`         | per request                          | $0.0063 |
| `reverse_geocode` | per request                          | $0.0063 |
| `directions`      | per request                          | $0.0063 |
| `distance_matrix` | per element (origins × destinations) | $0.0063 |
| `text_search`     | per request                          | $0.040  |
| `nearby_search`   | per request                          | $0.040  |
| `place_details`   | per request                          | $0.0213 |

## `geocode` [#geocode]

Convert a street address into coordinates. Returns a `results` array; ambiguous addresses can match more than once.

| Field       | Type   | Required | Notes               |
| ----------- | ------ | -------- | ------------------- |
| `operation` | string | yes      | `"geocode"`         |
| `address`   | string | yes      | The street address. |

## `reverse_geocode` [#reverse_geocode]

Convert coordinates into an address. Returns a `results` array, one entry per granularity (street address, neighborhood, locality).

| Field       | Type   | Required | Notes               |
| ----------- | ------ | -------- | ------------------- |
| `operation` | string | yes      | `"reverse_geocode"` |
| `latitude`  | number | yes      |                     |
| `longitude` | number | yes      |                     |

## `directions` [#directions]

A route between two points with turn-by-turn steps. Returns a single `result` with `distance`, `duration`, `startAddress`, `endAddress`, and `steps`.

| Field         | Type   | Required | Notes                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `operation`   | string | yes      | `"directions"`                                          |
| `origin`      | string | yes      | Address or `"lat,lng"`.                                 |
| `destination` | string | yes      | Address or `"lat,lng"`.                                 |
| `mode`        | string | no       | `driving` (default), `walking`, `bicycling`, `transit`. |

## `distance_matrix` [#distance_matrix]

Travel distance and time for every origin and destination pair. `results` is ordered as the cartesian product of origins × destinations, and each element carries its own `status` (`OK`, `ZERO_RESULTS`).

| Field          | Type      | Required | Notes                             |
| -------------- | --------- | -------- | --------------------------------- |
| `operation`    | string    | yes      | `"distance_matrix"`               |
| `origins`      | string\[] | yes      | Addresses or `"lat,lng"` strings. |
| `destinations` | string\[] | yes      | Addresses or `"lat,lng"` strings. |
| `mode`         | string    | no       | As for `directions`.              |

## `text_search` [#text_search]

Search places by free text ("pizza near Times Square").

| Field            | Type    | Required | Notes                                                     |
| ---------------- | ------- | -------- | --------------------------------------------------------- |
| `operation`      | string  | yes      | `"text_search"`                                           |
| `textQuery`      | string  | yes      |                                                           |
| `locationBias`   | object  | no       | `{ circle: { center: { latitude, longitude }, radius } }` |
| `includedType`   | string  | no       | Restrict to a place type (`restaurant`, `cafe`).          |
| `maxResultCount` | integer | no       | 1 to 20. Default 20.                                      |
| `rankPreference` | string  | no       | `RELEVANCE` (default) or `DISTANCE`.                      |
| `openNow`        | boolean | no       | Only places open now.                                     |
| `minRating`      | number  | no       | 0 to 5.                                                   |
| `languageCode`   | string  | no       | `en`, for instance.                                       |
| `regionCode`     | string  | no       | Two-character CLDR region code.                           |

Each result carries `id` (the Place ID, which `place_details` takes as `placeId`), `displayName`, `formattedAddress`, `latitude`, `longitude`, `types`, `rating`, `userRatingCount`, `priceLevel`, `websiteUri`, `phoneNumber`, `businessStatus`, `openNow`, `weekdayHours`, and `editorialSummary`.

## `nearby_search` [#nearby_search]

Places within a radius. Same result shape as `text_search`.

| Field                 | Type      | Required | Notes                                                                                    |
| --------------------- | --------- | -------- | ---------------------------------------------------------------------------------------- |
| `operation`           | string    | yes      | `"nearby_search"`                                                                        |
| `locationRestriction` | object    | yes      | `{ circle: { center: { latitude, longitude }, radius } }`, radius in meters, max 50,000. |
| `includedTypes`       | string\[] | no       | Place types to include.                                                                  |
| `excludedTypes`       | string\[] | no       | Place types to exclude.                                                                  |
| `maxResultCount`      | integer   | no       | 1 to 20. Default 20.                                                                     |
| `rankPreference`      | string    | no       | `POPULARITY` (default) or `DISTANCE`.                                                    |
| `languageCode`        | string    | no       |                                                                                          |
| `regionCode`          | string    | no       |                                                                                          |

## `place_details` [#place_details]

Details for one place by its Google Place ID. Returns a single `result` with the Pro-tier fields above.

| Field          | Type   | Required | Notes                                         |
| -------------- | ------ | -------- | --------------------------------------------- |
| `operation`    | string | yes      | `"place_details"`                             |
| `placeId`      | string | yes      | A place's `id` from a previous search result. |
| `languageCode` | string | no       |                                               |
| `regionCode`   | string | no       |                                               |

## Example [#example]

```sh
curl -s -X POST https://cloud.generalinput.com/v1/platform/geolocation \
  -H "Authorization: Bearer $GI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"geocode","address":"1600 Amphitheatre Parkway, Mountain View, CA"}'
```