Roadtrippers Developer Hub

Welcome to the Roadtrippers Developer Hub. You'll find comprehensive guides and documentation to help you start working with Roadtrippers as quickly as possible, as well as support if you get stuck. Let's jump right in!

Autocomplete

Autocomplete uses a text search and returns the most relevant travel matches. It takes a simple string input and can optionally filter by tags and geographic bounds

Autocomplete Requests

Requests use the endpoint https://api.boone.ai/api/v2/autocomplete.

📘

Authentication

Autocomplete requires basic auth. You need to pass the client id through either a request header or query param. This allows for the Autocomplete endpoint to be used in client-side​ code and without a proxy.

Required Parameters

Name

Description

input

Text to filter.

Optional Parameters

Name

Description

center

A point to restrict or promote places within a radius (required). Read more about location biasing and strict bounds.

Format the point as pair of comma separated decimal values, ,. For example, -84.51199,39.10803 (a point in Cincinnati, Ohio).

Latitude: -90 < y < 90
Longitude: -180 < x < 180

radius

Radius in meters around a center point to either bias or limit results. Read more about location biasing and strict bounds.

tags

Comma separated list of canonical tag public ids to search for or to exclude (e.g., points-of-interest,sports,attractions. Tags can be found via the tags endpoint.

Specifying tags to include will filter regions from results. However, specifying tags to exclude will not filter out regions.

strict_bounds

Limit results to those included in the radius around the center when "1". Disable location biasing.

Default is 0 (false).

chains

Comma separated list of chain public ids to search for or to exclude (e.g., walmart). Chains can be found via the Chains API.

locations

Filter results to specific countries and regions.

| separated of list of country codes country:US and region_ids region_id:6
See country codes and Regions reference.

For example, country:CA|country:MX|country:US would limit a search to North America.

region_id:1883|region_id:1852 would limit a search to results in Ohio (1883) or Kentucky (1852)

Locations filter will take precedence over other bounds.

This is an experimental feature

min_fidelity

Optional. Filters on matching fidelity_level equal to or above the given value.
Cannot exceed max_fidelity
Accepts values 1-5.

max_fidelity

Optional. Filters on matching fidelity_level equal to or lower than the given value.
Accepts values 1-5.

Location Biasing vs Strict Bounds

Location biasing allows you to prioritize results at a specific location. Rather than a strict cutoff, it allows you to surface locations that are farther away yet match your input query, but at the same time promote results closer to the center point. This is the default autocomplete behavior.

Setting strict_bounds to "1" will use a strict cutoff and limit results to those within the radius.

Example Request

https://api.boone.ai/api/v2/autocomplete?input=hotel&locations=country:US&center=-84.51199,39.10803&radius=16094

Autocomplete Responses

Autocomplete responses include two root level elements:

  • data contains an array of results matching the search in the format of GeoJSON features.
  • meta contains details about the search request.

Autocomplete Results

Results are formatted as GeoJSON features inside the root data element. They are ordered by relevance.

Currently, the geometries are limited to type of "Point" with coordinates in default GeoJSON format, an array of longitude,latitude values.

The GeoJSON properties include:

  • id is the unique id of this feature. Currently, this refers to a place id or region id depending on the type.
  • type is either "regions" or "canoncial_places". Locations like neighborhoods, cities, states, and countries are of type "regions", while everything else is of type "canonical_places" (e.g. businesses, restaurants, parks).
  • name is the name of the place or region.
  • address is a string that provides a street address relative to the type. For example, canonical_places might have a full address with street number and name, while a regions might just specify a state and country.
  • icon is the name of an icon that references Icons.
  • thumbnail is an image thumbnail, when available.
  • travel_rank is our ranking of the importance of a place in regards to travel and tourism.

Example Response

A successful status code is 200.

{
  "data": [    
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -84.4898275,
          39.0885358
        ]
      },
      "properties": {
        "id": 54798993,
        "type": "canonical_places",
        "name": "Carabello Coffee",
        "alt_names": [],
        "address": "107 East 9th Street, Newport, OH, United States",
        "icon": "restaurant",
        "thumbnail": null,
        "travel_rank": "0.546373"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -84.54017,
          39.16303
        ]
      },
      "properties": {
        "id": 52324821,
        "type": "canonical_places",
        "name": "Sidewinder Coffee and Tea",
        "alt_names": [],
        "address": "4181 Hamilton Ave, Ste 1, Cincinnati, OH, United States",
        "icon": "restaurant",
        "thumbnail": null,
        "travel_rank": "0.555907"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -84.55335438823009,
          39.048321095407914
        ]
      },
      "properties": {
        "id": 46078584,
        "type": "canonical_places",
        "name": "Starbucks Coffee",
        "alt_names": [],
        "address": "",
        "icon": "restaurant",
        "thumbnail": null,
        "travel_rank": "0.519029"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -84.503059080834,
          39.132361021057285
        ]
      },
      "properties": {
        "id": 51681733,
        "type": "canonical_places",
        "name": "Highland Coffee Shop",
        "alt_names": [],
        "address": "",
        "icon": "restaurant",
        "thumbnail": null,
        "travel_rank": "0.551656"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -84.518248736858,
          39.11592301733
        ]
      },
      "properties": {
        "id": 55179326,
        "type": "canonical_places",
        "name": "Deeper Roots Coffee Findlay",
        "alt_names": [],
        "address": "1814 Race St., , Cincinnati, OH, US",
        "icon": "restaurant",
        "thumbnail": null,
        "travel_rank": "0.546784"
      }
    }
  ],
  "meta": {
    "query": {
      "input": "coffee"
    }
  }
}

Updated 5 months ago

Autocomplete


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.