Upgrade from v2

The third iteration of the API (v3) brings breaking changes which include schema changes, new data like travel advisories and language phrases as well as removal of some country data.

Changes are grouped into few main groups - new base URL, internationalization (i18n), changes in a schema (data structures) with minimal added/removed data, new, moved and removed categories.

Notice: Newly available city data, endpoints, and categories are not included here due to them being brand new - previously unavailable in v2 and therefore there is nothing to transition from.

Base URL

Base URL is changed from https://api.thebasetrip.com/v2 to https://api.thebasetrip.com/v3. API key and authorization mechanism are unchanged.


Internationalization is fully supported through Accept-Language header. For more see Getting started.

Data structures

Money object, present in mobilePhone, tipping and driving categories is now standardized as follows:

    "amount": 82.68,
    "amountInteger": 8268,
    "currency": "USD",
    "displayAs": "$82.68"

Website object, previously just a regular string is now standardized as following object which will be upgraded in the future with additional attributes:

    "url": "https://www.example.com"
  • changed basic.name.sanitized to basic.slug
  • removed basic.name.native
  • added basic.languages.alpha2
  • changed basic.languages.code to basic.languages.alpha3
  • added basic.capital.slug
  • added basic.capital.href which points to the city data
  • changed basic.location.region and basic.location.subregion to objects with id and name which is i18n
  • removed basic.ituRegion
  • added basic.governmentTravelInfoUrl if from country is specified and data is available
  • changed currency object to currencies array
  • changed tipping.categories.tip.amount.type - moved one level up to tipping.categories.tip.type
  • changed tipping.categories.tip.amount.currency to alpha3 currency code
  • changed driving.road.entities.website to object with url attribute
  • added driving.road.petrol.fuel.price Money object
  • changed mobilePhone.carriers.website to object with url attribute

Added country categories

  • added category
  • added category

Moved country categories

  • changed from country to city level (eg. New York as a destination will yield different embassy from Washington D.C.), available only on Business and Enterprise plans

Removed country categories

  • removed category
  • removed category
  • removed category
  • removed category