Goal

To use city names to get the details for 1 (or more) cities and in 1 (or more) currencies. The endpoint is get_cities_details_by_name POST.

About Form Data (required parameters)

In the Request Body send Form Data with the parameters cities and currencies.

Both are required JSON objects and they represent the cities you want to get information for and the currencies that you want the prices/values in. Take a look at the Example section of this tutorial for an example or, alternatively, check the Example in the Endpoints tab.

Example

Let’s imagine you want to get information about Lisbon, Paris, Hamilton and San Francisco. Adding to that, you want to get all the prices/values for those cities in 3 different currencies: Euro, US Dollar and Suisse Franc.

Request Body / Form Data

Parameter cities:

[
    {
        "country": "Portugal",
        "name": "Lisbon"
    },
    {
        "country": "Spain *(example of a wrong country)*",
        "name": "Paris"
    },
    {
        "country": "Bermuda",
        "name": "Hamilton"
    },
    {
        "country": "United States",
        "name": "Saint Francisc *(example of a wrong city name)*"
    }
]

Parameter currencies:

[
   "Euro *(example of a wrong currency code)*",
   "USD",
   "CHF"
]

Notes about the Parameters

• The Parameters are JSON objects. Be aware of single quotes vs double quotes, or escaping/not-escaping special characters, for example.
• Since there’s no Paris in Spain, Paris would not be returned in the results. Please use the endpoint get_cities_list to get all the available ones and their respective countries. For example, for Hamilton, the dataset contains more than 1 (Bermuda, Canada, etc.)
• Some typos in San Francisco makes it also not be returned in the results. The request is made as an exact match. Fuzzy matching along with some flexibility could be introduced in the future if needed.
• The code for the Euro is EUR, which means the results would not contain any data in the Euro. Please use the endpoint get_currencies_list to get all the available currencies and the code to use. Accepting multiple codes for the same currency (in this case, accepting either Euro or EUR) could be introduced in the future if needed.

Results

{
   "data": [
      {
         "cost_of_living_details": [
            {
               "currency": "USD",
               "details": [
                  {
                     "Item": "1 Pair of Nike Running Shoes (Mid-Range)",
                     "Range": "54.49-108.97",
                     "Value": "82.96"
                  },
                  {
                     "Item": "1 Pair of Men Leather Business Shoes",
                     "Range": "54.49-145.3",
                     "Value": "93.16"
                  },
                  {
                     "Item": "Apartment (1 bedroom) in City Centre",
                     "Range": "847.56-1331.88",
                     "Value": "998.29"
                  },
                  {
                     "Item": "Apartment (1 bedroom) Outside of Centre",
                     "Range": "605.4-968.64",
                     "Value": "769.84"
                  },
                  {
                     "Item": "Average Monthly Net Salary (After Tax)",
                     "Range": "N/A",
                     "Value": "1270.18"
                  },
                  {
                     "Item": "Mortgage Interest Rate in Percentages (%), Yearly, for 20 Years Fixed-Rate",
                     "Range": "1.45-3.63",
                     "Value": "2.57"
                  }
               ]
            },
            {
               "currency": "CHF",
               "details": [
                  {
                     "Item": "Estimated Monthly Costs Without Rent",
                     "Range": "N/A",
                     "Value": "601.38"
                  },
                  {
                     "Item": "Meal, Inexpensive Restaurant",
                     "Range": "6.48-12.96",
                     "Value": "8.64"
                  },
                  {
                     "Item": "Meal for 2 People, Mid-range Restaurant, Three-course",
                     "Range": "27.01-59.42",
                     "Value": "37.81"
                  },
                  {
                     "Item": "McMeal at McDonalds (or Equivalent Combo Meal)",
                     "Range": "6.48-7.56",
                     "Value": "7.02"
                  },
                  {
                     "Item": "Domestic Beer (0.5 liter draught)",
                     "Range": "1.08-3.65",
                     "Value": "2.16"
                  },
                  {
                     "Item": "Imported Beer (0.33 liter bottle)",
                     "Range": "2.16-5.4",
                     "Value": "3.24"
                  },
                  {
                     "Item": "Cappuccino (regular)",
                     "Range": "0.76-3.24",
                     "Value": "1.81"
                  },
                  {
                     "Item": "Coke/Pepsi (0.33 liter bottle)",
                     "Range": "1.08-2.16",
                     "Value": "1.5"
                  }
               ]
            }
         ],
         "cost_of_living_index": "54.66",
         "cost_of_living_plus_rent_index": "44.23",
         "country": "Portugal",
         "groceries_index": "42.14",
         "last_updated_timestamp": "2021-02-13 19:35:20.566810+00:00",
         "local_purchasing_power_index": "47.87",
         "name": "Lisbon",
         "rent_index": "32.38",
         "restaurant_price_index": "47.61",
         "us_state": "N/A"
      },
      {
         "cost_of_living_details": [
            {
               "currency": "USD",
               "details": [
                  {
                     "Item": "Meal for 2 People, Mid-range Restaurant, Three-course",
                     "Range": "119.88-199.79",
                     "Value": "139.86"
                  },
                  {
                     "Item": "McMeal at McDonalds (or Equivalent Combo Meal)",
                     "Range": "11.99-16.99",
                     "Value": "14.99"
                  }
                  {
                     "Item": "Imported Beer (0.33 liter bottle)",
                     "Range": "9.0-13.98",
                     "Value": "9.99"
                  },
                  {
                     "Item": "Cappuccino (regular)",
                     "Range": "3.0-5.99",
                     "Value": "5.27"
                  },
                  {
                     "Item": "Coke/Pepsi (0.33 liter bottle)",
                     "Range": "2.0-3.5",
                     "Value": "2.82"
                  }
               ]
            },
            {
               "currency": "CHF",
               "details": [
                  {
                     "Item": "Mortgage Interest Rate in Percentages (%), Yearly, for 20 Years Fixed-Rate",
                     "Range": "5.94-8.1",
                     "Value": "7.27"
                  }
               ]
            }
         ],
         "cost_of_living_index": "146.91",
         "cost_of_living_plus_rent_index": "122.91",
         "country": "Bermuda",
         "groceries_index": "144.42",
         "last_updated_timestamp": "2021-02-13 19:31:32.033652+00:00",
         "local_purchasing_power_index": "93.49",
         "name": "Hamilton",
         "rent_index": "95.61",
         "restaurant_price_index": "157.89",
         "us_state": "N/A"
      }
   ]
}

Notes about the Results

• The results only include the valid cities and currencies in the request body. In this example, only Lisbon and Hamilton, with the prices/values in USD and CHF were valid arguments to the endpoint.
• The results shown here as an example do not include all the possible items that the data contains. Please take a look at the example Response in the Endpoints section, for the endpoint get_cities_details_by_name.