Geo-Parity Housing.json API

openapi: 3.2.0
info:
  title: Geo-Parity Housing.json API
  version: 1.0.0
  description: 'Free, key-less JSON APIs behind geo-parity.com: purchasing power parity, fair global salaries, Schengen 90/180 compliance, cross-timezone meetings, contractor economics, freelance rates, tax-residency day counts, country comparison, cloud region latency, and a digital-nomad visa directory. All GET responses are cacheable; errors return { ok:false, code, message, example }. No key is required: anonymous callers get 1,500 requests/month per IP plus a 30/minute burst cap. An optional API key (Authorization: Bearer gp_live_..., created at /account) only raises those ceilings — responses are identical either way, and a key is metered per account rather than per key. Every response carries X-RateLimit-Limit / -Remaining / -Reset (the minute window) and X-Quota-Limit / -Remaining / -Reset (the calendar month, resetting on the 1st UTC); exceeding either returns 429 with Retry-After and code RATE_LIMITED (slow down) or QUOTA_EXCEEDED (allowance spent — retrying will not help). Figures are informational estimates, not financial/tax/legal advice. Machine discovery: /llms.txt and /.well-known/mcp.json; the same tools are also registered with the browser''s WebMCP ModelContext on every page, executing through /api/mcp.'
  contact:
    url: https://geo-parity.com
servers:
- url: https://geo-parity.com
security:
- {}
- bearerAuth: []
- apiKeyQuery: []
tags:
- name: Housing.json
paths:
  /api/housing.json:
    get:
      operationId: compareHousing
      summary: Housing cost and affordability by country
      description: 'Rent measured against two different incomes at once: the caller''s remote income and the local median wage. The gap between those shares is the arbitrage. Also price-to-income and price-to-rent, each expressed as a percentage of that country''s own long-run average (127% means 27% less affordable than its historical norm) rather than as an absolute ratio, so comparing two countries'' percentages against each other is meaningless. Euro-area mortgage rates from the ECB; outside the euro area the field is absent rather than approximated. Every row carries rentBasis: measured rows use real published Eurostat city rents (Spain, Portugal, Switzerland), modelled rows are derived from the site''s price basket, which against Eurostat''s housing price level errs in both directions - understating by up to ~36% where housing has decoupled from the general price level (Ireland, Denmark, Czechia) and overstating by ~60% in Turkiye. National averages; not a quote for any tenancy, and not financial advice.'
      parameters:
      - name: sort
        in: query
        required: false
        description: Metric to rank by. Default affordability (rent as a share of the caller's remote income).
        schema:
          type: string
          enum:
          - affordability
          - rent
          - localBurden
          - priceToIncome
          default: affordability
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2 code; echoes that country's row, rank and measured city count.
        schema:
          type: string
      - name: remoteIncome
        in: query
        required: false
        description: Monthly remote income in USD. Drives the share-of-your-income and arbitrage-gap figures; omitted, those are absent.
        schema:
          type: number
          exclusiveMinimum: 0
      - name: maxRentPctOfIncome
        in: query
        required: false
        description: Keep only countries where rent is at or below this share of the caller's remote income (%).
        schema:
          type: number
          minimum: 0
      - name: flatM2
        in: query
        required: false
        description: Flat size in square metres used to turn a per-m2 rent into a monthly figure. Default 70.
        schema:
          type: number
          exclusiveMinimum: 0
      responses:
        '200':
          description: Ranked countries with rentBasis, per-metric reference years, a count of countries excluded for want of the sorted metric, and an attribution block.
        '400':
          description: Invalid parameter (bad sort, or a non-positive income, filter or flat size).
        '422':
          description: Unknown country code.
      tags:
      - Housing.json
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Optional Geo-Parity API key (gp_live_...), created at /account. Raises the monthly quota and per-minute burst; never changes a response. Metered per account, so extra keys do not add allowance.
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: The same key, for clients that cannot set headers.
externalDocs:
  description: 'Developer guide: quota ladder, error codes, API keys and MCP setup'
  url: https://geo-parity.com/developers/