Skip to content
IndepAI API Docs

Get City Recommendations

GET
/api/v1/geo/recommendations

Get personalized city recommendations based on budget and preferences. Accepts query parameters for budget, preferences (comma-separated), and limit.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
budget

Monthly budget in USD

number
> 0
Example
2500
preferences

Comma-separated preference tags

string
Example
safety,internet,climate
limit

Number of recommendations to return

integer
>= 1 <= 50
Example
10

Responses

Section titled “ Responses ”

200

Section titled “200 ”

City recommendations

object
success
required
boolean
data
required
object
recommendations
required
Array<object>
object
city
required
object
id
required

City identifier

string
Example
lisbon-portugal
name
required

City name

string
Example
Lisbon
country
required

Country name

string
Example
Portugal
countryCode
required

ISO 3166-1 alpha-2 country code

string
>= 2 characters <= 2 characters
Example
PT
region
required

Geographic region

string
Example
Western Europe
coordinates
required

City coordinates

object
lat
required
number
>= -90 <= 90
lng
required
number
>= -180 <= 180
Example
{
  "lat": 38.7223,
  "lng": -9.1393
}
costOfLiving
required
object
monthlyTotal
required

Total monthly cost of living (EUR)

number
Example
1800
housing
required

Monthly housing cost (EUR)

number
Example
900
food
required

Monthly food cost (EUR)

number
Example
350
transportation
required

Monthly transportation cost (EUR)

number
Example
50
utilities
required

Monthly utilities cost (EUR)

number
Example
100
entertainment
required

Monthly entertainment cost (EUR)

number
Example
200
other
required

Other monthly costs (EUR)

number
Example
200
qualityOfLife
required
object
overall
required

Overall quality of life score (0-100)

number
<= 100
Example
75
safety
required

Safety score (0-100)

number
<= 100
Example
80
healthcare
required

Healthcare quality score (0-100)

number
<= 100
Example
70
climate
required

Climate score (0-100)

number
<= 100
Example
85
internet
required

Internet quality score (0-100)

number
<= 100
Example
75
englishFriendly
required

English-friendliness score (0-100)

number
<= 100
Example
70
taxInfo
required
object
incomeTaxRate
required

Top marginal income tax rate (%)

number
<= 100
Example
48
capitalGainsTaxRate
required

Capital gains tax rate (%)

number
<= 100
Example
28
specialPrograms
required

Available special tax programs

Array<string>
Example
[
  "NHR (Non-Habitual Resident)"
]
nomadScore
required

Overall nomad-friendliness score (0-100)

number
<= 100
Example
82
visaInfo
required
object
schengen
required

Is in Schengen area

boolean
digitalNomadVisa
required

Offers digital nomad visa

boolean
visaFreeFor
required

Countries with visa-free access

Array<string>
Example
[
  "US",
  "UK",
  "CA",
  "AU"
]
currency
required

Local currency code

string
>= 3 characters <= 3 characters
Example
EUR
lastUpdated
required

Last data update timestamp

string format: date-time
matchScore
required

How well this city matches preferences

number
<= 100
savingsPerMonth
required

Monthly savings compared to current location

number
fiYearsGained
required

Additional FI runway years at this location

number
highlights
required

Key highlights for this recommendation

Array<string>
Example
[
  "50% lower cost of living",
  "Excellent healthcare",
  "Digital nomad visa available"
]
summary
required
object
potentialSavings
required

Average potential monthly savings

number
avgFiYearsGained
required

Average additional FI years across recommendations

number
meta
required
object
timestamp
required
string format: date-time

400

Section titled “400 ”

Validation error

object
success
required

Always false for error responses

boolean
error
required

Error type

string
Example
Validation error
code

Machine-readable error code

string
Example
VALIDATION_ERROR
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
Example
currentAge
message
required

Error message

string
Example
Must be between 18 and 100