Geo-Parity Country Fit.json API

openapi: 3.2.0
info:
  title: Geo-Parity Country Fit.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: Country Fit.json
paths:
  /api/country-fit.json:
    get:
      operationId: findCountryFit
      summary: Countries ranked by your own weights on quality and cost
      description: Blends the livability composite with budget reach by 0–10 weights; region, budget and visa are filters. A POST with `preferences` (words) is for paid plans and uses TypeSafe Jev to turn them into weights; GET is free. For information only; every response says so first.
      parameters:
      - name: budget
        in: query
        schema:
          type: number
          minimum: 1
        description: Monthly budget in USD (default 3000)
      - name: cost
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 10
        description: Weight 0–10 for cost (default 5)
      - name: internet
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 10
        description: Weight 0–10 for internet (default 5)
      - name: safety
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 10
        description: Weight 0–10 for safety (default 5)
      - name: healthcare
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 10
        description: Weight 0–10 for healthcare (default 5)
      - name: air
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 10
        description: Weight 0–10 for air (default 5)
      - name: english
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 10
        description: Weight 0–10 for english (default 5)
      - name: region
        in: query
        schema:
          type: string
          enum:
          - East Asia & Pacific
          - Europe & Central Asia
          - Latin America & Caribbean
          - Middle East, North Africa, Afghanistan & Pakistan
          - North America
          - South Asia
          - Sub-Saharan Africa
        description: World Bank region filter
      - name: withinBudget
        in: query
        schema:
          type: string
          enum:
          - '0'
          - '1'
        description: 1 (default) keeps only countries the budget covers
      - name: needsVisa
        in: query
        schema:
          type: string
          enum:
          - '1'
        description: Keep only countries with a nomad visa the budget meets
      - name: limit
        in: query
        schema:
          type: number
          minimum: 1
        description: Maximum rows (default 10)
      responses:
        '200':
          description: Match groups (qualify, nearMiss, unpublished, excluded, none), one entry, or comparison rows; attribution names the curated register
        '400':
          description: No parameter (MISSING_PARAMS), a non-positive funds figure or bad period (INVALID_PARAM), or fewer than two countries (TOO_FEW)
        '422':
          description: A country outside the spine (UNKNOWN_COUNTRY) or an unsupported currency (UNKNOWN_CURRENCY)
      tags:
      - Country Fit.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/