Expatistan APIexpatistan.com ↗
Access Expatistan's cost of living data for cities and countries worldwide. Compare prices, view rankings, and retrieve itemized expenses across 6 categories.
What is the Expatistan API?
The Expatistan API exposes cost of living data across 7 endpoints, covering itemized prices in 6 categories — Food, Housing, Clothes, Transportation, Personal Care, and Entertainment — for cities and countries worldwide. The compare_cities endpoint returns a side-by-side percentage breakdown between any two cities, while get_city_rankings lists cities by price index with optional regional filtering.
curl -X GET 'https://api.parse.bot/scraper/de9d469c-5a9e-40ae-ab39-abdd0b916473/get_city_cost_of_living?city_slug=london' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace expatistan-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Expatistan SDK — cost of living data, comparisons, and rankings."""
from parse_apis.Expatistan_API import Expatistan, Region, LocationNotFound
client = Expatistan()
# Search for a city by name to find its slug
city_result = client.city_summaries.search(query="london", limit=1).first()
print(city_result.name, city_result.country_code, city_result.slug)
# Drill into the full cost of living detail for that city
city = city_result.details()
print(city.city, city.summary.family_of_four_monthly_cost, city.summary.single_person_monthly_cost)
# Compare that city with another
comparison = city.compare_with(city2_slug="paris")
print(comparison.summary)
for detail in comparison.comparison_details[:3]:
print(detail.category, detail.item, detail.difference)
# List city rankings filtered by region
for ranking in client.city_rankings.list(region=Region.EUROPE, limit=5):
print(ranking.rank, ranking.city, ranking.price_index)
# List country rankings and navigate to full detail
country_ranking = client.country_rankings.list(limit=1).first()
try:
country = country_ranking.details()
print(country.country, country.summary.single_person_monthly_cost)
except LocationNotFound as exc:
print(f"Country not found: {exc}")
# Get recent homepage data
recent = client.recent_datas.get()
for comp in recent.recent_comparisons[:3]:
print(comp.text, comp.url)
print("exercised: city_summaries.search / city.details / city.compare_with / city_rankings.list / country_rankings.list / country.details / recent_datas.get")
Get detailed cost of living data for a specific city. Returns itemized prices across categories (Food, Housing, Clothes, Transportation, Personal Care, Entertainment) and monthly cost estimates for a single person and a family of four. Each price item includes the item description and local-currency price string.
| Param | Type | Description |
|---|---|---|
| city_slugrequired | string | The city slug identifier (e.g. 'london', 'new-york-city', 'paris'). Use search_city_autocomplete to find valid slugs. |
{
"type": "object",
"fields": {
"city": "string, city name with country",
"slug": "string, the city slug used in the request",
"prices": "object with category keys (Food, Housing, Clothes, Transportation, Personal Care, Entertainment) each containing an array of objects with item and price",
"summary": "object with family_of_four_monthly_cost and single_person_monthly_cost as currency strings"
},
"sample": {
"data": {
"city": "London, United Kingdom",
"slug": "london",
"prices": {
"Food": [
{
"item": "Basic lunchtime menu (including a drink) in the business district",
"price": "£15"
},
{
"item": "Combo meal in fast food restaurant (big mac meal or similar)",
"price": "£10"
}
],
"Housing": [
{
"item": "Monthly rent for 85 m2 (900 sqft) furnished accommodation in expensive area",
"price": "£3,019"
}
]
},
"summary": {
"single_person_monthly_cost": "£3,733",
"family_of_four_monthly_cost": "£6,237"
}
},
"status": "success"
}
}About the Expatistan API
City and Country Cost Data
The get_city_cost_of_living and get_country_cost_of_living endpoints both accept a slug parameter — city_slug or country_slug respectively — and return prices organized under six category keys: Food, Housing, Clothes, Transportation, Personal Care, and Entertainment. Each category holds an array of individual price items. The summary object on both endpoints includes family_of_four_monthly_cost and single_person_monthly_cost, giving a quick aggregate without summing line items manually. Use search_city_autocomplete with a query string to resolve a city name to its valid handle (slug) before calling the detail endpoints.
City and Country Rankings
get_city_rankings returns a ranked array of cities with rank, city, slug, and price_index fields. It accepts an optional region parameter — valid values include world, europe, north-america, latin-america, asia, middle-east, and africa among others — letting you scope results to a specific part of the world. get_country_rankings takes no parameters and returns the same shape for countries, ordered from most to least expensive.
City Comparisons
compare_cities takes two slug parameters (city1_slug, city2_slug) and returns a summary string with the overall percentage difference, plus a comparison_details array. Each item in comparison_details includes the category, item name, the price in each city, and the percentage difference, making it straightforward to identify which expense categories drive the gap between two locations.
Recent Activity
get_recent_data requires no inputs and returns two arrays: recent_prices (strings describing newly submitted price entries) and recent_comparisons (objects with a text description and a URL). This endpoint reflects the crowd-sourced nature of Expatistan's dataset, where individual contributors submit local prices.
The Expatistan API is a managed, monitored endpoint for expatistan.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when expatistan.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official expatistan.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a relocation calculator that uses
compare_citiesto show salary-adjusted cost differences between a user's current city and a target city. - Populate a country research dashboard with
get_country_cost_of_livingsummary fields for monthly living cost estimates. - Filter
get_city_rankingsby region to display the top 10 cheapest cities in Asia or Europe for a digital nomad guide. - Use
search_city_autocompleteto power a city search typeahead before fetching full cost breakdowns. - Generate housing and food cost comparisons for an HR tool that calculates cost-of-living adjustments for international transfers.
- Monitor
get_recent_datato surface newly submitted local prices and flag significant changes in specific categories. - Aggregate
get_country_rankingsdata to visualize global cost-of-living distribution on a choropleth map.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Expatistan offer an official developer API?+
What does the `compare_cities` endpoint actually return beyond a summary sentence?+
comparison_details array where each element includes the expense category, the specific item name, the price in each city, and the percentage difference between them. This lets you pinpoint which individual items — such as rent or groceries — account for the most cost variation, rather than relying only on the top-level summary string.Does the API expose historical cost of living data or price trends over time?+
get_recent_data. You can fork this API on Parse and revise it to add an endpoint that tracks or caches price snapshots over time.How complete is city coverage, and does it include smaller cities?+
search_city_autocomplete endpoint will return results only for cities that exist in the Expatistan database. If a city you need is missing, you can fork the API on Parse and revise it to supplement with additional data sources.