TripEdge

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 500). Optional, default: 50.

  • Name
    types
    Type
    string
    Description

    Comma-separated list of place types to include: "country", "city", "area", "hotel". Any combination is allowed, e.g. types=city,area,country. Optional, default: all types. Note: countries are not geo-indexed, so they only appear in text searches, never in coordinate searches.

  • Name
    type
    Type
    string
    Description

    Legacy single-type filter. Ignored when types is provided. Optional.

  • Name
    limit
    Type
    integer
    Description

    Maximum number of results to return (1 to 1000). Optional, default: 20.

  • Name
    language
    Type
    string
    Description

    Localizes place names and formatted addresses. Supported values: en, fr, es, pt (default en). lang is accepted as an alias. Places without a translation fall back to English. Text matching is language-independent: a query in any supported language (e.g. "Bruxelles") matches regardless of the language value.

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.

  • Name
    language
    Type
    string
    Description

    Localizes the place name and formatted address. Supported values: en, fr, es, pt (default en). lang is accepted as an alias.

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 (en, fr, es, or pt) — echoes the requested language.

  • 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/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, maximum 500 km), sorted by distance with the nearest first, capped at limit results (default 20, maximum 1000). Use types to restrict results to any combination of place types — for example types=city,area,country to exclude hotels.

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 500). Default: 50.

  • Name
    types
    Type
    string
    Description

    Comma-separated list of place types to include: "country", "city", "area", "hotel". Countries only appear in text searches (they are not geo-indexed). Invalid values return a 400 error.

  • Name
    type
    Type
    string
    Description

    Legacy single-type filter. Ignored when types is provided.

  • Name
    limit
    Type
    integer
    Description

    Maximum number of results to return (1 to 1000). Default: 20.

  • Name
    language
    Type
    string
    Description

    Localizes place names and formatted addresses in the results. Supported values: en, fr, es, pt (default en). lang is accepted as an alias. Queries match place names in any supported language regardless of this value.

Search by coordinates

Request

GET
/places/search
curl -G https://api.tripedge.com/places/search \
  -H "Authorization: Bearer {token}" \
  -d latitude=40.7127753 \
  -d longitude=-74.0059728 \
  -d radius_km=100 \
  -d types=city,area \
  -d limit=100

Response

{
  "data": {
    "results": [
      {
        "place_id": "25128",
        "display_name": "New York",
        "formatted_address": "New York, New York",
        "type": "city",
        "coordinates": {
          "lat": 40.7127753,
          "long": -74.0059728
        }
      },
      {
        "place_id": "312345",
        "display_name": "SoHo",
        "formatted_address": "SoHo, New York, New York",
        "type": "area",
        "coordinates": {
          "lat": 40.723301,
          "long": -74.002988
        }
      }
    ]
  },
  "success": true,
  "message": null
}

Request

GET
/places/search
curl -G https://api.tripedge.com/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/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.

Query parameters

  • Name
    language
    Type
    string
    Description

    Localizes the place name and formatted address. Supported values: en, fr, es, pt (default en). lang is accepted as an alias.

Request

GET
/places/25128
curl https://api.tripedge.com/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).

Was this page helpful?