{"openapi":"3.1.0","info":{"title":"Cost of Life API","version":"1.0.0","description":"Cost-of-living, salary, tax, comparison and city-recommendation engines for 70 cities. All figures are modelled estimates for comparison between cities, not financial or tax advice. When quoting a figure, state the household it was priced for.","license":{"name":"Data available for non-commercial use with attribution"}},"servers":[{"url":"https://cost-of-life.com"}],"paths":{"/api/cities":{"get":{"summary":"List every city with its headline monthly cost and index","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by city or country name"},{"name":"currency","in":"query","schema":{"type":"string","enum":["AED","ARS","AUD","BRL","CAD","CHF","CLP","COP","CZK","DKK","EUR","GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN","MYR","NOK","NZD","PHP","PLN","QAR","RON","RSD","SAR","SEK","SGD","THB","TRY","TWD","USD","VND","ZAR"]}}],"responses":{"200":{"description":"City list"}}}},"/api/cost":{"post":{"summary":"Monthly cost breakdown for a household in a city","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["city"],"properties":{"city":{"type":"string","enum":["abu-dhabi","amsterdam","athens","auckland","austin","bali","bangalore","bangkok","barcelona","belgrade","berlin","brisbane","bucharest","budapest","buenos-aires","chennai","chiang-mai","chicago","copenhagen","delhi","doha","dubai","dublin","ho-chi-minh-city","hong-kong","hyderabad","istanbul","krakow","kuala-lumpur","lisbon","london","los-angeles","madrid","manchester","manila","medellin","melbourne","mexico-city","miami","milan","montreal","mumbai","munich","new-york","osaka","paris","porto","prague","pune","riyadh","rome","san-francisco","santiago","sao-paulo","seattle","seoul","singapore","split","stockholm","sydney","taipei","tallinn","tel-aviv","tokyo","toronto","valencia","vancouver","vienna","warsaw","zurich"]},"currency":{"type":"string","enum":["AED","ARS","AUD","BRL","CAD","CHF","CLP","COP","CZK","DKK","EUR","GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN","MYR","NOK","NZD","PHP","PLN","QAR","RON","RSD","SAR","SEK","SGD","THB","TRY","TWD","USD","VND","ZAR"],"default":"USD"},"household":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":6,"default":1},"children":{"type":"integer","minimum":0,"maximum":6,"default":0},"lifestyle":{"type":"string","enum":["lean","moderate","comfortable","premium"],"default":"moderate"},"housing":{"type":"string","enum":["room","1bed-outer","1bed-centre","3bed-outer","3bed-centre"],"default":"1bed-centre"},"car":{"type":"boolean","default":false},"privateHealthcare":{"type":"boolean","default":false},"childcare":{"type":"boolean","default":false},"intlSchool":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Itemised breakdown,each line carrying the assumption behind it"}}}},"/api/salary":{"post":{"summary":"Equivalent gross salary between two cities, solved for equal monthly surplus","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to","grossAnnual"],"properties":{"from":{"type":"string","enum":["abu-dhabi","amsterdam","athens","auckland","austin","bali","bangalore","bangkok","barcelona","belgrade","berlin","brisbane","bucharest","budapest","buenos-aires","chennai","chiang-mai","chicago","copenhagen","delhi","doha","dubai","dublin","ho-chi-minh-city","hong-kong","hyderabad","istanbul","krakow","kuala-lumpur","lisbon","london","los-angeles","madrid","manchester","manila","medellin","melbourne","mexico-city","miami","milan","montreal","mumbai","munich","new-york","osaka","paris","porto","prague","pune","riyadh","rome","san-francisco","santiago","sao-paulo","seattle","seoul","singapore","split","stockholm","sydney","taipei","tallinn","tel-aviv","tokyo","toronto","valencia","vancouver","vienna","warsaw","zurich"]},"to":{"type":"string","enum":["abu-dhabi","amsterdam","athens","auckland","austin","bali","bangalore","bangkok","barcelona","belgrade","berlin","brisbane","bucharest","budapest","buenos-aires","chennai","chiang-mai","chicago","copenhagen","delhi","doha","dubai","dublin","ho-chi-minh-city","hong-kong","hyderabad","istanbul","krakow","kuala-lumpur","lisbon","london","los-angeles","madrid","manchester","manila","medellin","melbourne","mexico-city","miami","milan","montreal","mumbai","munich","new-york","osaka","paris","porto","prague","pune","riyadh","rome","san-francisco","santiago","sao-paulo","seattle","seoul","singapore","split","stockholm","sydney","taipei","tallinn","tel-aviv","tokyo","toronto","valencia","vancouver","vienna","warsaw","zurich"]},"grossAnnual":{"type":"number","minimum":0},"currency":{"type":"string","enum":["AED","ARS","AUD","BRL","CAD","CHF","CLP","COP","CZK","DKK","EUR","GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN","MYR","NOK","NZD","PHP","PLN","QAR","RON","RSD","SAR","SEK","SGD","THB","TRY","TWD","USD","VND","ZAR"],"default":"USD"},"household":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":6,"default":1},"children":{"type":"integer","minimum":0,"maximum":6,"default":0},"lifestyle":{"type":"string","enum":["lean","moderate","comfortable","premium"],"default":"moderate"},"housing":{"type":"string","enum":["room","1bed-outer","1bed-centre","3bed-outer","3bed-centre"],"default":"1bed-centre"},"car":{"type":"boolean","default":false},"privateHealthcare":{"type":"boolean","default":false},"childcare":{"type":"boolean","default":false},"intlSchool":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Both sides with tax breakdown and the required gross"}}}},"/api/afford":{"post":{"summary":"Whether an income covers a city at a given lifestyle","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["city","income"],"properties":{"city":{"type":"string","enum":["abu-dhabi","amsterdam","athens","auckland","austin","bali","bangalore","bangkok","barcelona","belgrade","berlin","brisbane","bucharest","budapest","buenos-aires","chennai","chiang-mai","chicago","copenhagen","delhi","doha","dubai","dublin","ho-chi-minh-city","hong-kong","hyderabad","istanbul","krakow","kuala-lumpur","lisbon","london","los-angeles","madrid","manchester","manila","medellin","melbourne","mexico-city","miami","milan","montreal","mumbai","munich","new-york","osaka","paris","porto","prague","pune","riyadh","rome","san-francisco","santiago","sao-paulo","seattle","seoul","singapore","split","stockholm","sydney","taipei","tallinn","tel-aviv","tokyo","toronto","valencia","vancouver","vienna","warsaw","zurich"]},"income":{"type":"number","minimum":0},"incomeIsNet":{"type":"boolean","default":false},"currency":{"type":"string","enum":["AED","ARS","AUD","BRL","CAD","CHF","CLP","COP","CZK","DKK","EUR","GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN","MYR","NOK","NZD","PHP","PLN","QAR","RON","RSD","SAR","SEK","SGD","THB","TRY","TWD","USD","VND","ZAR"],"default":"USD"},"household":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":6,"default":1},"children":{"type":"integer","minimum":0,"maximum":6,"default":0},"lifestyle":{"type":"string","enum":["lean","moderate","comfortable","premium"],"default":"moderate"},"housing":{"type":"string","enum":["room","1bed-outer","1bed-centre","3bed-outer","3bed-centre"],"default":"1bed-centre"},"car":{"type":"boolean","default":false},"privateHealthcare":{"type":"boolean","default":false},"childcare":{"type":"boolean","default":false},"intlSchool":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Disposable income, savings rate, score and verdict"}}}},"/api/compare":{"post":{"summary":"Two cities side by side across cost, tax, housing, quality of life and climate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["a","b"],"properties":{"a":{"type":"string","enum":["abu-dhabi","amsterdam","athens","auckland","austin","bali","bangalore","bangkok","barcelona","belgrade","berlin","brisbane","bucharest","budapest","buenos-aires","chennai","chiang-mai","chicago","copenhagen","delhi","doha","dubai","dublin","ho-chi-minh-city","hong-kong","hyderabad","istanbul","krakow","kuala-lumpur","lisbon","london","los-angeles","madrid","manchester","manila","medellin","melbourne","mexico-city","miami","milan","montreal","mumbai","munich","new-york","osaka","paris","porto","prague","pune","riyadh","rome","san-francisco","santiago","sao-paulo","seattle","seoul","singapore","split","stockholm","sydney","taipei","tallinn","tel-aviv","tokyo","toronto","valencia","vancouver","vienna","warsaw","zurich"]},"b":{"type":"string","enum":["abu-dhabi","amsterdam","athens","auckland","austin","bali","bangalore","bangkok","barcelona","belgrade","berlin","brisbane","bucharest","budapest","buenos-aires","chennai","chiang-mai","chicago","copenhagen","delhi","doha","dubai","dublin","ho-chi-minh-city","hong-kong","hyderabad","istanbul","krakow","kuala-lumpur","lisbon","london","los-angeles","madrid","manchester","manila","medellin","melbourne","mexico-city","miami","milan","montreal","mumbai","munich","new-york","osaka","paris","porto","prague","pune","riyadh","rome","san-francisco","santiago","sao-paulo","seattle","seoul","singapore","split","stockholm","sydney","taipei","tallinn","tel-aviv","tokyo","toronto","valencia","vancouver","vienna","warsaw","zurich"]},"grossAnnual":{"type":"number"},"currency":{"type":"string","enum":["AED","ARS","AUD","BRL","CAD","CHF","CLP","COP","CZK","DKK","EUR","GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN","MYR","NOK","NZD","PHP","PLN","QAR","RON","RSD","SAR","SEK","SGD","THB","TRY","TWD","USD","VND","ZAR"],"default":"USD"},"household":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":6,"default":1},"children":{"type":"integer","minimum":0,"maximum":6,"default":0},"lifestyle":{"type":"string","enum":["lean","moderate","comfortable","premium"],"default":"moderate"},"housing":{"type":"string","enum":["room","1bed-outer","1bed-centre","3bed-outer","3bed-centre"],"default":"1bed-centre"},"car":{"type":"boolean","default":false},"privateHealthcare":{"type":"boolean","default":false},"childcare":{"type":"boolean","default":false},"intlSchool":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Row-by-row comparison with a winner per ranked metric"}}}},"/api/recommend":{"post":{"summary":"Rank all cities against weighted preferences","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["weights"],"properties":{"weights":{"type":"object","description":"Each 0-10. Relative size is what matters, not the absolute value.","properties":{"cost":{"type":"number","minimum":0,"maximum":10},"safety":{"type":"number","minimum":0,"maximum":10},"weather":{"type":"number","minimum":0,"maximum":10},"healthcare":{"type":"number","minimum":0,"maximum":10},"transport":{"type":"number","minimum":0,"maximum":10},"nightlife":{"type":"number","minimum":0,"maximum":10},"family":{"type":"number","minimum":0,"maximum":10},"english":{"type":"number","minimum":0,"maximum":10},"beach":{"type":"number","minimum":0,"maximum":10},"internet":{"type":"number","minimum":0,"maximum":10}}},"income":{"type":"number","description":"Gross annual. Enables real disposable-income scoring."},"maxMonthlyCost":{"type":"number"},"climate":{"type":"string","enum":["warm","mild","cool","any"],"default":"any"},"regions":{"type":"array","items":{"type":"string"}},"requireNomadVisa":{"type":"boolean"},"requireCoastal":{"type":"boolean"},"limit":{"type":"integer","minimum":1,"maximum":70,"default":12},"currency":{"type":"string","enum":["AED","ARS","AUD","BRL","CAD","CHF","CLP","COP","CZK","DKK","EUR","GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN","MYR","NOK","NZD","PHP","PLN","QAR","RON","RSD","SAR","SEK","SGD","THB","TRY","TWD","USD","VND","ZAR"],"default":"USD"},"household":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":6,"default":1},"children":{"type":"integer","minimum":0,"maximum":6,"default":0},"lifestyle":{"type":"string","enum":["lean","moderate","comfortable","premium"],"default":"moderate"},"housing":{"type":"string","enum":["room","1bed-outer","1bed-centre","3bed-outer","3bed-centre"],"default":"1bed-centre"},"car":{"type":"boolean","default":false},"privateHealthcare":{"type":"boolean","default":false},"childcare":{"type":"boolean","default":false},"intlSchool":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Ranked cities with per-dimension scores and reasons"}}}}}}