Skip to content
IndepAI API Docs

Compare Cities

POST
/api/v1/geo/compare
curl --request POST \
  --url https://indepai.app/api/v1/geo/compare \
  --header 'Content-Type: application/json' \
  --data '{ "cities": [ "lisbon-portugal", "barcelona-spain", "berlin-germany" ], "monthlyBudget": 2500, "priorities": { "cost": 5, "safety": 5, "climate": 5, "internet": 5, "healthcare": 5 } }'

Compare multiple cities side by side

Request Body

Section titled “Request Body”
Media typeapplication/json
object
cities
required

City IDs to compare

Array<string>
>= 2 items <= 5 items
Example
[
  "lisbon-portugal",
  "barcelona-spain",
  "berlin-germany"
]
monthlyBudget

Monthly budget for affordability calculation

number
> 0
Example
2500
priorities

Priority weights for scoring (0-10)

object
cost
number
default: 5 <= 10
safety
number
default: 5 <= 10
climate
number
default: 5 <= 10
internet
number
default: 5 <= 10
healthcare
number
default: 5 <= 10

Responses

Section titled “Responses”

200

Section titled “200”

City comparison

Media typeapplication/json
object
success
required
boolean
data
required
object
cities
required
Array<object>
object
id
required

City identifier

string
name
required

City name

string
country
required

Country name

string
countryCode
required

ISO 3166-1 alpha-2 country code

string
>= 2 characters <= 2 characters
region
required

Geographic region

string
coordinates
required

City coordinates

object
lat
required
number
>= -90 <= 90
lng
required
number
>= -180 <= 180
costOfLiving
required
object
monthlyTotal
required

Total monthly cost of living (EUR)

number
housing
required

Monthly housing cost (EUR)

number
food
required

Monthly food cost (EUR)

number
transportation
required

Monthly transportation cost (EUR)

number
utilities
required

Monthly utilities cost (EUR)

number
entertainment
required

Monthly entertainment cost (EUR)

number
other
required

Other monthly costs (EUR)

number
qualityOfLife
required
object
overall
required

Overall quality of life score (0-100)

number
<= 100
safety
required

Safety score (0-100)

number
<= 100
healthcare
required

Healthcare quality score (0-100)

number
<= 100
climate
required

Climate score (0-100)

number
<= 100
internet
required

Internet quality score (0-100)

number
<= 100
englishFriendly
required

English-friendliness score (0-100)

number
<= 100
taxInfo
required
object
incomeTaxRate
required

Top marginal income tax rate (%)

number
<= 100
capitalGainsTaxRate
required

Capital gains tax rate (%)

number
<= 100
specialPrograms
required

Available special tax programs

Array<string>
nomadScore
required

Overall nomad-friendliness score (0-100)

number
<= 100
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>
currency
required

Local currency code

string
>= 3 characters <= 3 characters
lastUpdated
required

Last data update timestamp

string format: date-time
rankings
required
Array<object>
object
cityId
required
string
overallScore
required
number
<= 100
rank
required
integer
> 0
scoreBreakdown
required
object
cost
required
number
safety
required
number
climate
required
number
internet
required
number
healthcare
required
number
affordabilityYears
required

Years of FI runway at this location

number | null
recommendation
required

AI-generated recommendation based on priorities

string
meta
required
object
timestamp
required
string format: date-time
Example
{
  "success": true,
  "data": {
    "cities": [
      {
        "id": "lisbon-portugal",
        "name": "Lisbon",
        "country": "Portugal",
        "countryCode": "PT",
        "region": "Western Europe",
        "coordinates": {
          "lat": 38.7223,
          "lng": -9.1393
        },
        "costOfLiving": {
          "monthlyTotal": 1800,
          "housing": 900,
          "food": 350,
          "transportation": 50,
          "utilities": 100,
          "entertainment": 200,
          "other": 200
        },
        "qualityOfLife": {
          "overall": 75,
          "safety": 80,
          "healthcare": 70,
          "climate": 85,
          "internet": 75,
          "englishFriendly": 70
        },
        "taxInfo": {
          "incomeTaxRate": 48,
          "capitalGainsTaxRate": 28,
          "specialPrograms": [
            "NHR (Non-Habitual Resident)"
          ]
        },
        "nomadScore": 82,
        "visaInfo": {
          "visaFreeFor": [
            "US",
            "UK",
            "CA",
            "AU"
          ]
        },
        "currency": "EUR"
      }
    ]
  }
}

400

Section titled “400”

Validation error

Media typeapplication/json
object
success
required

Always false for error responses

boolean
error
required

Error type

string
code

Machine-readable error code

string
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
message
required

Error message

string
Example
{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}