BYT API

API Endpoints

Categories

/categories

Retrieves information about travel cost categories. Get the list of all categories, or just one by passing in an ID.
GET /categories
GET /categories/{id}
Parameters
Name Type Description
id optional number The ID of the category
Results
The returning data structure contains an array of category objects, or a single object if an ID is specified.
{
    status: true,
    data: [
        {
            "category_id": "1",
            "name": "Accommodation",
            "description": "From camping to luxury hotels, costs are for one person and assume double occupancy.",
            "sumtype": "1"
        },
        {},{},...
    ]
}

Countries

/countries

Retrieves information about countries. Get the list of all countries, or just one by passing in a 2-letter country code.
GET /countries
GET /countries/{country_code}
Parameters
Name Type Description
country_code optional string The 2-letter code of the country
Results
The returning data structure contains an array of country objects, or a single object if a country code is specified.
{
    status: true,
    data: [
        {
            "country_code": "00",
            "name": "At Sea",
            "currency_code": "USD",
            "negotiate": "0"
        },
        {
            "country_code": "AD",
            "name": "Andorra ",
            "currency_code": "EUR",
            "negotiate": "4"
        },
        {
            "country_code": "AE",
            "name": "United Arab Emirates ",
            "currency_code": "AED",
            "negotiate": "0"
        },
        {},{},...
    ]
}

Currencies

/currencies

Retrieves information about currencies. Get the list of all currencies, or just one by passing in a 3-letter ISO 4217 currency code.
GET /currencies
GET /currencies/{currency_code}
Parameters
Name Type Description
currency_code optional string The 3-letter code of the currency
Results

The returning data structure will contain an array of currency objects, or just one currency object.

Note Not every currency object contains a symbol variable. If the desired currency does not contain a symbol, it is customary to display the amount with the 3-letter currency code in place of the symbol. (For example, "CFA 5,000")

{
    status: true,
    data: [
        ...,{},{},
        {
            "currency_code": "ARS",
            "currency": "Neuvo Peso (Argentina)",
            "symbol": "AR$"
        },
        {
            "currency_code": "AUD",
            "currency": "Dollar (Australia) ",
            "symbol": "AU$"
        },
        {
            "currency_code": "AWG",
            "currency": "Guilder/Florin (Aruba)",
            "symbol": "À"
        },
        {},{},...
    ]
}

/currencies/convert

Performs currency conversion with the 2 given currencies, and optional amount value.

Note Currency conversion rates should not be relied on for actual trading or currency purchases. The provided rates are not guaranteed to be accurate, as they are delayed and/or cached for various periods of time. The provided currency exchange rates should only be used for reference and informational purposes.

GET /currencies/convert/{from}/{to}
GET /currencies/convert/{from}/{to}/{amount}
Parameters
Name Type Description
from string The 3-letter currency code of the currency to convert from
to string The 3-letter currency code of the currency to convert to
amount optional number A value amount, defaults to 1.00 if not included
Results

The returning data structure contains an object with the rate and the new currency amount in newAmount.

The following example shows a request to convert $15 U.S. Dollars (USD) to Euros (EUR). The response contains the conversion rate and the value in Euros.

/currencies/convert/usd/eur/15
{
    status: true,
    data: {
        "from": "usd",
        "to": "eur",
        "originalAmount": 15,
        "rate": 0.900900900901,
        "newAmount": 13.5135135135
    }
}

Locations

/locations

Retrieves information about locations.
GET /locations/{geonameid}
Parameters
Name Type Description
geonameid number The unique id of the location
Results

The returning data structure will contain a location object. This object will contain data about the location such as the name, state/province, country, currency, and geographic coordinates.

{
    status: true,
    data: {
        "geonameid": "4167147",
        "name": "Orlando",
        "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",
        "admin1_code": "FL",
        "timezone": "America/New_York",
        "country_name": "United States of America ",
        "negotiate": "0",
        "currency_code": "USD",
        "currency": "Dollar (United States)",
        "symbol": "$",
        "statename": "Florida"
    }
}

/search/locationdata

Searches for a location by name that contains travel cost data. This will search only locations in the system which have travel cost data (approximately 3,000, and growing every week). If you wish to search across all locations, see /search/location above.

Searches will query against the name and alternative names fields in the system. As many cities have multiple names, this will help bring up relevant search results. Furthermore, some countries (U.S., Canada, and a few others) also have zip and postal codes listed in their alternative names, so it is possible to perform a postal code search for a location.

GET /search/locationdata/{name}
Parameters
Name Type Description
name string The name, or partial name, of the location to search for
Results

The returning data structure will contain an array of location objects. Use the geonameid variable for future requests for travel cost data and other information.

{
    status: true,
    data: [
        {
            "geonameid": "4167147",
            "name": "Orlando",
            "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",
            "admin1_code": "FL",
            "timezone": "America/New_York",
            "country_name": "United States of America ",
            "negotiate": "0",
            "currency_code": "USD",
            "currency": "Dollar (United States)",
            "symbol": "$",
            "statename": "Florida"
        },
        {},{},...
    ]
}

/search/geo

Searches for locations by geographic coordinates, and returns locations in close proximity. This will search all locations in the system (about 160,000), whether or not they have travel cost data. If you only wish to search for locations with travel cost data, see /search/geodata below.

Note This is a resource-intensive operation. Consumers of this request should cache the results until the user has significantly changed their location, perhaps by 25 miles (40km) or more. Otherwise, the search results will not change and the system will be taxed unnecessarily.

GET /search/geo/{latitude}/{longitude}
Parameters
Name Type Description
latitude number The latitude component of the location
longitude number The longitude component of the location
Results

The returning data structure will contain an array of location objects. Use the geonameid variable for future requests for travel cost data and other information.

{
    status: true,
    data: [
        {
            "geonameid": "4167147",
            "name": "Orlando",
            "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",
            "admin1_code": "FL",
            "timezone": "America/New_York",
            "country_name": "United States of America ",
            "negotiate": "0",
            "currency_code": "USD",
            "currency": "Dollar (United States)",
            "symbol": "$",
            "statename": "Florida"
        },
        {},{},...
    ]
}

/search/geodata

Searches for locations by geographic coordinates, and returns locations in close proximity. This will search only locations in the system which have travel cost data (approximately 3,000, and growing every week). If you wish to search across all locations, see /search/geo above.

Note This is a resource-intensive operation. Consumers of this request should cache the results until the user has significantly changed their location, perhaps by 25 miles (40km) or more. Otherwise, the search results will not change and the system will be taxed unnecessarily.

GET /search/geodata/{latitude}/{longitude}
Parameters
Name Type Description
latitude number The latitude component of the location
longitude number The longitude component of the location
Results

The returning data structure will contain an array of location objects. Use the geonameid variable for future requests for travel cost data and other information.

{
    status: true,
    data: [
        {
            "geonameid": "4167147",
            "name": "Orlando",
            "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",
            "admin1_code": "FL",
            "timezone": "America/New_York",
            "country_name": "United States of America ",
            "negotiate": "0",
            "currency_code": "USD",
            "currency": "Dollar (United States)",
            "symbol": "$",
            "statename": "Florida"
        },
        {},{},...
    ]
}

Travel Costs

/costs/country

Retrieves travel cost data for a country.

GET /costs/country/{country_code}
Parameters
Name Type Description
country_code string The 2-letter country code of the country
Results

The returning data structure contains an array of travel cost objects, containing the typical travel costs for low-end (budget), mid-range, and luxury budgets for each category.

Note that the last object will have a category_id of 0, which is the overall total average cost for this country. Note that these total costs are not a direct sum of all of the category costs, but instead are a specifically calculated amount based on actual travel spending.

The travel cost amounts are in the local currency. To get this currency, obtain the details about the country from the /country/{country_code} endpoint.

Note In many cases, not all categories for a location will have travel costs data, and will be missing in the response data.

{
    status: true,
    data: [
        {
            "category_id": "1",
            "value_budget": "38.8013100707",
            "value_midrange": "104.392131639",
            "value_luxury": "299.572858268",
            "country_code": "US"
        },
        {
            "category_id": "2",
            "value_budget": "61.1363066818",
            "value_midrange": "160.104241209",
            "value_luxury": "435.734672656",
            "country_code": "US"
        },
        {},{},...,
        {
            "value_budget": "72.1210366696",
            "value_midrange": "194.279380744",
            "value_luxury": "558.836906124",
            "country_code": "US",
            "category_id": "0"
        }
    ]
}

/costs/locationinfo

Retrieves travel cost data for a location, along with information about the location.

GET /costs/locationinfo/{geonameid}
Parameters
Name Type Description
geonameid number The unique id (geoname id) of the location
Results

The returning data structure contains an array with 2 keys: "costs" and "info". The "costs" key of the array contains the typical travel costs for low-end (budget), mid-range, and luxury budgets for each category. The "info" key of the array contains data about the city such as the name, lat/lng, URL, population, etc.

Note that the last object will have a category_id of 0, which is the overall total average cost for this location. Note that these total costs are not a direct sum of all of the category costs, but instead are a specifically calculated amount based on actual travel spending.

The travel cost amounts are in the local currency. To get this currency, obtain the details about the location from the /location/{geonameid} endpoint.

Note In many cases, not all categories for a location will have travel costs data, and will be missing in the response data.

Note If the location does not have enough travel cost data to calculate a daily average, then the data value will be set to false. This means that our system does not have travel cost data for this location.

{
	"status":true,
	"data":{
		"costs":
			[
				{
					"category_id":"1",
					"value_budget":"44.066821377509",
					"value_midrange":"122.9595291765",
					"value_luxury":"376.69098739016",
					"geonameid":"5128581"
				},
				{...},
				{...},
				...
			],
		"info":
			{
				"geonameid":"5128581",
				"name":"New York City",
				"asciiname":"New York City",
				"latitude":"40.7142691000",
				"longitude":"-74.0059729000",
				"feature_class":"P",
				"feature_code":"PPL",
				"country_code":"US",
				"admin1_code":"NY",
				"timezone":"America\/New_York",
				"country_name":"United States of America",
				"currency_code":"USD",
				"currency":"Dollar (United States)",
				"symbol":"$",
				"statename":"New York",
				"url":"http:\/\/www.budgetyourtrip.com\/united-states-of-america\/new-york-city"
			}
	}
}

/costs/location

Retrieves travel cost data for a location.

GET /costs/location/{geonameid}
Parameters
Name Type Description
geonameid number The unique id (geoname id) of the location
Results

The returning data structure contains an array of travel cost objects, containing the typical travel costs for low-end (budget), mid-range, and luxury budgets for each category.

Note that the last object will have a category_id of 0, which is the overall total average cost for this location. Note that these total costs are not a direct sum of all of the category costs, but instead are a specifically calculated amount based on actual travel spending.

The travel cost amounts are in the local currency. To get this currency, obtain the details about the location from the /location/{geonameid} endpoint.

Note In many cases, not all categories for a location will have travel costs data, and will be missing in the response data.

Note If the location does not have enough travel cost data to calculate a daily average, then the data value will be set to false. This means that our system does not have travel cost data for this location.

{
    status: true,
    data: [
        {
            "category_id": "1",
            "value_budget": "28.8283804572",
            "value_midrange": "78.608090767",
            "value_luxury": "231.253493979",
            "geonameid": "2988507"
        },
        {
            "category_id": "2",
            "value_budget": "20.6112419345",
            "value_midrange": "56.5147812001",
            "value_luxury": "167.930090327",
            "geonameid": "2988507"
        },
        {},{},...,
        {
            "value_budget": "46.7539020441",
            "value_midrange": "124.232080451",
            "value_luxury": "348.080379669",
            "geonameid": "2988507",
            "category_id": "0"
        }
    ]
}

/costs/highlights

Retrieves travel highlights for a location. Highlights are specific curated examples of actual costs in a location. For example, "Lunch at a restaurant, $35".

GET /costs/highlights/{geonameid}
Parameters
Name Type Description
geonameid number The unique id (geoname id) of the location
Results

The returning data structure contains an array of highlight objects, containing the specific cost examples for the location.

The travel cost amounts are in the local currency. To get this currency, obtain the details about the location from the /location/{geonameid} endpoint.

Note In many cases, locations will not have highlights, and the results will be an empty array.

{
    status: true,
    data: [
        {
            "description": "Taxi around town",
            "category_id": "2",
            "cost": "75",
        },
        {},{},...
    ]
}

Accommodation

/accommodation/geosearch

Retrieves a list of accommodation options near the specified coordinates.

GET /accommodation/geosearch/{latitude}/{longitude}
Parameters
Name Type Description
latitude number The latitude component of the location
longitude number The longitude component of the location
Results

The returning data structure contains an array of accommodation (hotel or hostel) objects.

Note It is against the Terms of Use to modify or change the URL component of the accommodation data.

{
    status: true,
    data: [
        {
            "id": "10239",
            "name": "Al Sharq Hotel",
            "description": "AL SHARQ HOTEL is located in city centre of Sharjah , just 12 KM away from Dubai Airport, walking distance to Dubai bus station , museums ,shopping malls , and beach. The hotel is Surrounded with many restaurants and supermarkets with free Delivery to your room.",
            "url": "http://www.hostelbookers.com/hostels/united-arab-emirates/sharjah/10239/?affiliate=budgetyourtrip",
            "longitude": "55.3738296031952",
            "latitude": "25.3296941562006",
            "dormavailable": "N",
            "dormprice": "0",
            "dormcurrency": "USD",
            "privateavailable": "Y",
            "privateprice": "22.5",
            "privatecurrency": "USD",
            "rating_overall": "83.64",
            "addr1": "P.O. Box. 20201",
            "addr2": "",
            "addr3": "",
            "zip": "20201",
            "city": "Sharjah",
            "country": "United Arab Emirates"
        }
        {},{},...
    ]
}

/accommodation/location

Retrieves a list of accommodation options for a specified location (geonameid)

GET /accommodation/location/{geonameid}
Parameters
Name Type Description
geonameid int The unique id of the geoname to retrieve data for
Results

The returning data structure contains an array of accommodation (hotel or hostel) objects.

Note It is against the Terms of Use to modify or change the URL component of the accommodation data.

{
    status: true,
    data: [
        {
            "id": "10239",
            "name": "Al Sharq Hotel",
            "description": "AL SHARQ HOTEL is located in city centre of Sharjah , just 12 KM away from Dubai Airport, walking distance to Dubai bus station , museums ,shopping malls , and beach. The hotel is Surrounded with many restaurants and supermarkets with free Delivery to your room.",
            "url": "http://www.hostelbookers.com/hostels/united-arab-emirates/sharjah/10239/?affiliate=budgetyourtrip",
            "longitude": "55.3738296031952",
            "latitude": "25.3296941562006",
            "dormavailable": "N",
            "dormprice": "0",
            "dormcurrency": "USD",
            "privateavailable": "Y",
            "privateprice": "22.5",
            "privatecurrency": "USD",
            "rating_overall": "83.64",
            "addr1": "P.O. Box. 20201",
            "addr2": "",
            "addr3": "",
            "zip": "20201",
            "city": "Sharjah",
            "country": "United Arab Emirates"
        }
        {},{},...
    ]
}