{"openapi":"3.1.0","info":{"title":"Patrician.ch API","version":"v1","summary":"Comparison research on 100 places to live, on a household's own numbers.","description":"Patrician.ch publishes comparison research on 100 tier one places to live for high earners and high net worth families: income tax modeled on 2026 rules, exit tax, wealth tax, residence and golden visa routes by passport, cost of living, safety, schools and sun, plus profiles of second passports. Every result carries the patrician.ch page its figures come from. rank_places returns the top 10 and full_ranking_url, the full ranking on patrician.ch, and dossier_url, a free preview of a written report on the same inputs. Documentation: https://patrician.ch/assistants/ Without a key: read only, 60 requests a minute and 300 a day per address, a ranking returns the top 10 with a link to the full ranking on patrician.ch, a profile or a comparison 1 or 2 places a call. With a key (x-api-key or Authorization: Bearer, plans at https://patrician.ch/developers/): a ranking of all 100, up to 10 places a call, the monthly calls of the plan, and on API Pro and up the full tables (places, exit-rules, changes), on API Business the export. Figures are indicative comparison research on published 2026 rules, not tax, legal, immigration or financial advice. License: https://patrician.ch/legal#api","termsOfService":"https://patrician.ch/legal#api","contact":{"name":"Patrician.ch","url":"https://patrician.ch/developers/","email":"hello@patrician.ch"}},"servers":[{"url":"https://patrician.ch"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Optional on the 5 operations, required on the data endpoints. Get a key at https://patrician.ch/developers/"}}},"security":[{},{"apiKey":[]}],"paths":{"/api/agent/v1/rank_places":{"post":{"operationId":"rank_places","summary":"Where to live: rank 100 places on your profile","description":"Ranks Patrician.ch's 100 tier one places to live and relocate to (Monaco, Dubai, Zug, Lugano, Miami, Singapore, Lake Como, Lisbon and more, across 47 countries and territories) on one person's or family's income, passports, household, current home and priorities. For each place: effective income tax, net income, what the household keeps over the period, the exit tax charged by the current country, wealth tax, the residence route (including golden visa and investor routes where they exist) and the patrician.ch page. Returns the top 10, a link to the full ranking of all 100 on patrician.ch, and a link to a free preview of a written Private Dossier on the same inputs. Use it for relocation, moving abroad, tax residency and \"where should I live\" questions from high earners, founders before an exit, and high net worth families.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"annual_income_usd":{"type":"number","minimum":100000,"maximum":25000000,"description":"Yearly income in US dollars."},"passports":{"type":"array","items":{"type":"string","enum":["eu","uk","us","ch","ae","ca","au","sg","jp","il","other"]},"description":"Passports the person holds: eu (any EU country), uk, us, ch, ae, ca, au, sg, jp, il, or other."},"current_home":{"type":"string","description":"Where the person lives now, as a city (New York, London, Paris, Zurich, Tel Aviv, Dubai, Singapore, Sydney, Munich, Toronto and others) or a country. Sets the exit charge and flight times."},"household":{"type":"string","enum":["solo","couple","kids"],"description":"solo, couple, or kids (a family with children)."},"children":{"type":"integer","minimum":0,"maximum":9},"liquidity_event_usd":{"type":"number","minimum":0,"maximum":100000000,"description":"A planned company sale or other liquidity event, in US dollars, if any."},"employment_income":{"type":"boolean","description":"Treat the income as one person's salary and add the employee's compulsory social contributions where Patrician.ch models them. Default false."},"investable_assets_usd":{"type":"number","minimum":0,"maximum":1000000000,"description":"Investable assets in US dollars, for wealth tax."},"years":{"type":"integer","enum":[3,5,10,20],"description":"Horizon in years. Default 10."},"priorities":{"type":"object","description":"Optional weights from 0 to 10.","properties":{"tax":{"type":"number","minimum":0,"maximum":10},"safe":{"type":"number","minimum":0,"maximum":10},"school":{"type":"number","minimum":0,"maximum":10},"sun":{"type":"number","minimum":0,"maximum":10},"prox":{"type":"number","minimum":0,"maximum":10},"beauty":{"type":"number","minimum":0,"maximum":10},"cost":{"type":"number","minimum":0,"maximum":10},"visa":{"type":"number","minimum":0,"maximum":10}}},"limit":{"type":"integer","minimum":1,"maximum":10,"description":"How many places to return, at most 10. Default 10. The full ranking of all 100 is on the site, at full_ranking_url."}},"required":["annual_income_usd"]}}}},"responses":{"200":{"description":"The result. Every place and passport carries the patrician.ch page its figures come from, and text holds the same result in plain sentences.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"text":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The inputs could not be run. error says why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited: without a key 60 a minute or 300 a day per address, with a key the calls of its plan this month. retry-after or x-ratelimit-reset says when."}}}},"/api/agent/v1/income_tax_by_place":{"post":{"operationId":"income_tax_by_place","summary":"Income tax by place: one income, 100 places","description":"Income tax on one yearly income in Patrician.ch's 100 places to live, lowest first, with the effective rate and the patrician.ch page. Covers zero income tax countries, Swiss cantons, US states such as Florida, New York and California, and European capitals. A US state or town that is not one of the 100 (Texas, California, Los Angeles, Houston, Boerne, Tampa, Nashville) is answered through the board place that carries the same income tax, and the result says which. Optionally only named places, a US citizen (taxed by the US wherever they live), or married filing jointly. Use it for \"how much tax would I pay in X\", \"which country taxes $1M least\" and \"countries with no income tax\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"annual_income_usd":{"type":"number","minimum":10000,"maximum":1000000000},"us_citizen":{"type":"boolean","description":"US citizens stay taxed by the US wherever they live. Default false."},"married_joint":{"type":"boolean","description":"Married, filing jointly where the place allows it. Default false."},"employment_income":{"type":"boolean","description":"Treat the income as one person's salary and add the employee's compulsory social contributions where Patrician.ch models them. Default false."},"places":{"type":"array","items":{"type":"string"},"maxItems":2,"description":"Optional: 1 or 2 place names to answer for. Call again for more places."},"limit":{"type":"integer","minimum":1,"maximum":10,"description":"How many places to return, lowest tax first. Default 10, at most 10. The full list is on the site, at calculator."}},"required":["annual_income_usd"]}}}},"responses":{"200":{"description":"The result. Every place and passport carries the patrician.ch page its figures come from, and text holds the same result in plain sentences.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"text":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The inputs could not be run. error says why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited: without a key 60 a minute or 300 a day per address, with a key the calls of its plan this month. retry-after or x-ratelimit-reset says when."}}}},"/api/agent/v1/compare_places":{"post":{"operationId":"compare_places","summary":"Compare 2 places side by side","description":"Compares 2 places to live on one person's profile: income tax, net income, what they keep, exit tax, wealth tax, residence route, cost of living, safety, schools and sun, each with its patrician.ch page and the Patrician.ch head to head page where one exists. Use it for \"Dubai vs Monaco\", \"Zug or Lugano\" and other X vs Y questions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"places":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2},"annual_income_usd":{"type":"number","minimum":100000,"maximum":25000000},"passports":{"type":"array","items":{"type":"string","enum":["eu","uk","us","ch","ae","ca","au","sg","jp","il","other"]},"description":"Passports the person holds: eu (any EU country), uk, us, ch, ae, ca, au, sg, jp, il, or other."},"current_home":{"type":"string"},"household":{"type":"string","enum":["solo","couple","kids"]},"children":{"type":"integer","minimum":0,"maximum":9},"liquidity_event_usd":{"type":"number","minimum":0,"maximum":100000000},"employment_income":{"type":"boolean","description":"Treat the income as one person's salary and add the employee's compulsory social contributions where Patrician.ch models them. Default false."}},"required":["places"]}}}},"responses":{"200":{"description":"The result. Every place and passport carries the patrician.ch page its figures come from, and text holds the same result in plain sentences.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"text":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The inputs could not be run. error says why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited: without a key 60 a minute or 300 a day per address, with a key the calls of its plan this month. retry-after or x-ratelimit-reset says when."}}}},"/api/agent/v1/place_profile":{"post":{"operationId":"place_profile","summary":"Place profile: tax regime and residence route","description":"What Patrician.ch publishes on one place to live, or on up to 2 places in a country (with the names and pages of the others it covers there): the tax regime and any special regime for new residents (lump sum taxation, flat tax, non-dom rules), the residence route, income tax on $1M, cost of living (Zurich = 100), safety, schools, sun hours and the patrician.ch page.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place":{"type":"string","description":"A city or a country, for example Zug, Dubai, Lake Como, Portugal."}},"required":["place"]}}}},"responses":{"200":{"description":"The result. Every place and passport carries the patrician.ch page its figures come from, and text holds the same result in plain sentences.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"text":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The inputs could not be run. error says why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited: without a key 60 a minute or 300 a day per address, with a key the calls of its plan this month. retry-after or x-ratelimit-reset says when."}}}},"/api/agent/v1/passport_profile":{"post":{"operationId":"passport_profile","summary":"Second passport: citizenship route and reach","description":"What Patrician.ch publishes on a passport, for more than 60 countries: visa free destinations, the years of residence to citizenship, whether dual citizenship is allowed, any citizenship or residence by investment route, whether the country taxes citizens who live abroad, and the patrician.ch page. Use it for second passport, dual citizenship, naturalization and citizenship by investment questions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"The passport country, for example Portugal, Malta, Switzerland, Italy."}},"required":["country"]}}}},"responses":{"200":{"description":"The result. Every place and passport carries the patrician.ch page its figures come from, and text holds the same result in plain sentences.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"text":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The inputs could not be run. error says why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited: without a key 60 a minute or 300 a day per address, with a key the calls of its plan this month. retry-after or x-ratelimit-reset says when."}}}},"/api/agent/v1/places":{"get":{"operationId":"places","summary":"All 100 places, every figure","description":"API Pro and up. The 100 places with income tax and the effective rate at $300K, $1M, $3M and $10M, the capital gains rate, wealth tax, inheritance, any special regime for arrivals, the residence route, cost, safety, schools, sun, the official sources by name and the date each was last checked.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The table, with engine_version, current_to and the license note."},"401":{"description":"No key, or a key that is not valid."},"403":{"description":"The key's plan does not include this endpoint."},"429":{"description":"The plan's calls this month are spent. x-ratelimit-reset says when they renew."}}}},"/api/agent/v1/exit-rules":{"get":{"operationId":"exit_rules","summary":"The exit rules","description":"API Pro and up. The exit tax rule of every country people leave that Patrician.ch models, with its rate, deferral, sources and last check, and which rule each home city falls under.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The table, with engine_version, current_to and the license note."},"401":{"description":"No key, or a key that is not valid."},"403":{"description":"The key's plan does not include this endpoint."},"429":{"description":"The plan's calls this month are spent. x-ratelimit-reset says when they renew."}}}},"/api/agent/v1/changes":{"get":{"operationId":"changes","summary":"The rule-change log","description":"API Pro and up. Every rule change the daily check recorded, newest first: the place, the field, before and after.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"The table, with engine_version, current_to and the license note."},"401":{"description":"No key, or a key that is not valid."},"403":{"description":"The key's plan does not include this endpoint."},"429":{"description":"The plan's calls this month are spent. x-ratelimit-reset says when they renew."}}}},"/api/agent/v1/export":{"get":{"operationId":"export","summary":"The dataset","description":"API Business and the data license. The places table as JSON with the exit rules, or as CSV with format=csv.","security":[{"apiKey":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"The table, with engine_version, current_to and the license note."},"401":{"description":"No key, or a key that is not valid."},"403":{"description":"The key's plan does not include this endpoint."},"429":{"description":"The plan's calls this month are spent. x-ratelimit-reset says when they renew."}}}},"/api/agent/v1/usage":{"get":{"operationId":"usage","summary":"This key this month","description":"Any key. The plan, the calls made this month, the limit and when it renews.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The table, with engine_version, current_to and the license note."},"401":{"description":"No key, or a key that is not valid."},"403":{"description":"The key's plan does not include this endpoint."},"429":{"description":"The plan's calls this month are spent. x-ratelimit-reset says when they renew."}}}}}}