Getting Started

The Structure of the data

Currencies in the system are indexed by 3-letter ISO 4217 currency codes, and include the name of the currency and an optional symbol (such as "$").

Countries are indexed by 2-letter ISO 3166-1 country codes, and include the name of the country and some other relevant data.

Locations are based on the database, in which every city has a unique ID (the "geoname id"). Note that not every location in the database is in Budget Your Trip's database, although Budget Your Trip's database has over 160,000 locations. Around 3,000 locations have travel cost data associated with them.

Locations also have a local name, an "ascii" name (for presentation with standard ASCII characters), alternative names (names in foreign languages, zip codes, and other common references), geographic coordinates, and a variety of other information used to describe the type of location.

Locations and countries can be searched by name. Locations can also be searched by geographic coordinates (latitude and longitude).

Travel cost data can be retrieved for both countries and locations, assuming the location has data associated with it. This data will be organized by category, and the list of available categories can also be retrieved from the system.


Requests for data can be made over HTTPS or HTTP to the various endpoints available in our system. All requests must contain an API Key and will in turn respond with the data in the specified format (or JSON by default).


In order to use the Budget Your Trip API, you must obtain an API Key. If you have not already done so, read all about how to get one on the API Key page.

All requests must contain the API Key in the header variable X-API-KEY. For example:

The root URL of every API request will be


Some API endpoints require parameters. Parameters that are textual search terms must be URL ENCODED. That is, spaces should become %20.

Data Formats

By default, all responses are in JSON.

Other response formats are available by placing the format parameter at the end of the url. For example, ?format=xml will return data in XML. Available formats include json, xml, and php.

All responses contain at least 2 fields, data and status. The status variable will be true if the request and response were processed without any issues. If there was an error, status will be false and an error variable will contain a message explaining the problem. The data variable will contain all of the response objects or arrays, as per the specifications described for each endpoint.

A Brief Tutorial

To get the average travel costs for Orlando, you can first search for the location by name with /search/location/{NAME}, and then find the geoname id to get the travel costs with /costs/location/{GEONAMEID}.

And then you would receive the following response.
    "error": false,
    "data": [
            "geonameid": "4167147",
            "asciiname": "Orlando",
            "alternativenames": "32801,32802,32803,32804,32805,32806,32807,32808,32809,32810,32811,32812,32813,32814,32816,32817,32818,32819,32820,32821,32822,32824,32825,32826,32827,32828,32829,32830,32831,32832,32833,32834,32835,32836,32837,32839,32853,32854,32855,32856,32857,32858,32859,32860,32861,32862,32867,32868,32869,32872,32877,32878,32886,32887,32889,32890,32891,32893,32897,32898,Orlando,ao lan duo,orando,Орландо,××•×¨×œ× ×“×•,オーランド,奥兰多",
            "latitude": "28.5383355000",
            "longitude": "-81.3792365000",
            "feature_class": "P",
            "feature_code": "PPL",
            "country_code": "US",
            "cc2": "",
            "admin1_code": "FL",
            "admin2_code": "095",
            "score": "1",
            "currency_code": "USD",
            "currency": "Dollar (United States)",
            "symbol": "$",
            "countryname": "United States of America ",
            "has_states": "1",
            "statename": "Florida"

If you search by the name or a partial name, you will likely receive more than one response. As many cities have the same name (Paris, France and Paris, Texas, for example), you need to make sure you are selecting the correct location. In this case, you could present the search results to the user to make a selection. Or, if there is only one result, you could automatically select it. Either way, the geonameid in the response is the needed variable in order to take the next step: finding travel costs for a specific location.

Then, you can ask for the travel costs:


More code samples and client libraries can be found on the Samples page.

Reference Documentation

For specific details about endpoints and method calls, including parameters and response formats, please refer to the Endpoint Documentation.

Endpoint Documentation

Error Handling

If an error occurs in any request, the status variable in the response will be false. The error variable will contain an explanation of the error. For example:

        status: false,
        error: "A search term is required.",
        data: null

For errors such as the above, the response code will still be 200. A 404 error will be returned if the endpoint does not exist. A 403 error will be returned if the client does not have permission to access the endpoint (such as with an API Key failure or something similar).