Places

The places endpoints allow you to search for destinations and retrieve location details. Use these endpoints to help users find locations for their hotel searches.

The places endpoints require the same Bearer token authentication as the rest of the API.

The place models

PlaceSearchRequest object

Name
text_query
Type
string
Description
The search text (city name, address, landmark, etc.). Required unless latitude and longitude are provided. Min length: 1.
Name
latitude
Type
number
Description
Latitude for coordinate-based search (-90 to 90). Must be provided together with longitude.
Name
longitude
Type
number
Description
Longitude for coordinate-based search (-180 to 180). Must be provided together with latitude.
Name
radius_km
Type
number
Description
Search radius in kilometers for coordinate-based search (0.1 to 300). Optional, default: 50.
Name
type
Type
string
Description
Filter by place type: "city", "area", or "hotel" (optional).
Name
language
Type
string
Description
Response language code (e.g., "en", "es", "fr"). Optional.

PlaceSearchResponse object

Name
results
Type
array of PlaceSearchResult
Description
Array of matching places.

PlaceSearchResult object

Name
place_id
Type
string
Description
Unique identifier for the place. Pass it to the retrieve endpoint or to availability searches.
Name
display_name
Type
string
Description
Human-readable name for the place.
Name
formatted_address
Type
string
Description
Full formatted address.
Name
type
Type
string
Description
The place type: "city", "area", "hotel", or "country".
Name
coordinates
Type
Coordinates
Description
Geographic coordinates of the place, when available.

PlaceRetrieveRequest object

Name
place_id
Type
string
Description
The place identifier from a search result. Required. Min length: 1.

PlaceDetails object

Name
place_id
Type
string
Description
Unique identifier for the place.
Name
display_name
Type
string
Description
Human-readable name for the place.
Name
formatted_address
Type
string
Description
Full formatted address.
Name
types
Type
array of strings
Description
Array of place types.
Name
language
Type
string
Description
Language code of the response.
Name
coordinates
Type
Coordinates
Description
Geographic coordinates.

Coordinates object

Name
lat
Type
number
Description
Latitude.
Name
long
Type
number
Description
Longitude.

ApiResponse wrapper

All responses are wrapped in a standard API response format:

Name
data
Type
T
Description
The response data (PlaceSearchResponse or PlaceDetails).
Name
success
Type
boolean
Description
Whether the request was successful.
Name
message
Type
string
Description
Error message if unsuccessful.

GET/v1/places/search

Search places

Search for places by text query or by coordinates. Returns a list of matching destinations that can be used for hotel availability searches.

Provide either text_query for a text search, or latitude and longitude for a coordinate search. A coordinate search returns cities, areas, and hotels within radius_km of the given point (default 50 km), sorted by distance with the nearest first, capped at 20 results. Use type to restrict results to a single place type.

Parameters

Name
text_query
Type
string
Description
The search text (city name, address, landmark, etc.). Required unless latitude and longitude are provided.
Name
latitude
Type
number
Description
Latitude for coordinate-based search. Must be provided together with longitude.
Name
longitude
Type
number
Description
Longitude for coordinate-based search. Must be provided together with latitude.
Name
radius_km
Type
number
Description
Search radius in kilometers for coordinate-based search (0.1 to 300). Default: 50.
Name
type
Type
string
Description
Filter by place type: "city", "area", or "hotel".
Name
language
Type
string
Description
Response language code (e.g., "en", "es", "fr").

Search by coordinates

Request

GET

/v1/places/search

curl -G https://api.tripedge.com/v1/places/search \
  -H "Authorization: Bearer {token}" \
  -d latitude=40.7127753 \
  -d longitude=-74.0059728 \
  -d radius_km=10 \
  -d type=hotel

Response

{
  "data": {
    "results": [
      {
        "place_id": "412345",
        "display_name": "New York Hilton Midtown",
        "formatted_address": "New York, United States",
        "type": "hotel",
        "coordinates": {
          "lat": 40.7625,
          "long": -73.9793
        }
      }
    ]
  },
  "success": true,
  "message": null
}

Request

GET

/v1/places/search

curl -G https://api.tripedge.com/v1/places/search \
  -H "Authorization: Bearer {token}" \
  -d text_query="New York"

Response

{
  "data": {
    "results": [
      {
        "place_id": "25128",
        "display_name": "New York",
        "formatted_address": "New York, United States",
        "type": "city",
        "coordinates": {
          "lat": 40.7127753,
          "long": -74.0059728
        }
      },
      {
        "place_id": "412345",
        "display_name": "New York Hilton Midtown",
        "formatted_address": "New York, United States",
        "type": "hotel",
        "coordinates": {
          "lat": 40.7625,
          "long": -73.9793
        }
      }
    ]
  },
  "success": true,
  "message": null
}

GET/v1/places/:place_id

Retrieve place

Retrieves detailed information about a specific place, including its coordinates. Use the returned coordinates for availability searches when you have a place_id.

Path parameters

Name
place_id
Type
string
Description
The place identifier from a search result.

Request

GET

/v1/places/25128

curl https://api.tripedge.com/v1/places/25128 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "place_id": "25128",
    "display_name": "New York",
    "formatted_address": "New York, United States",
    "types": ["city"],
    "language": "en",
    "coordinates": {
      "lat": 40.7127753,
      "long": -74.0059728
    }
  },
  "success": true,
  "message": null
}

Using places with availability

After retrieving a place, you can use either the place_id directly or the coordinates in your availability search.

Using place_id

The simplest approach - pass the place_id directly to the availability endpoint:

{
  "place_id": "25128",
  "check_in": "2024-03-15",
  "check_out": "2024-03-18",
  "rooms": [{ "adults": 2, "children": 0, "children_ages": [] }]
}

Using coordinates

For more control over the search area, use coordinates with an optional radius:

{
  "coordinates": {
    "lat": 40.7127753,
    "long": -74.0059728
  },
  "radius": 10000,
  "check_in": "2024-03-15",
  "check_out": "2024-03-18",
  "rooms": [{ "adults": 2, "children": 0, "children_ages": [] }]
}

The radius parameter specifies the search radius in meters (default: 10000, max: 50000).