Geo-Parity Total Cost.json API

openapi: 3.2.0
info:
  title: Geo-Parity Total Cost.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: Total Cost.json
paths:
  /api/total-cost.json:
    get:
      operationId: compareTotalCost
      summary: Total monthly cost of living vs a stated income
      description: Sums rent, the everyday basket EXCLUDING rent, out-of-pocket healthcare, and income tax plus employee social contributions, then subtracts the total from a stated monthly income. The basket normally contains rent (47-58% of it), so a naive total that adds a housing figure to the full basket overstates by roughly 60%; this endpoint removes it. For US rows HUD Fair Market Rent is gross rent including tenant-paid utilities, so utilities are removed as well. VAT is never added - purchasing-power data derives from surveyed purchaser prices which already include indirect tax. Rent is measured wherever the housing dataset reaches (25 of the 41) and estimated from the basket for the remaining 16, which are tagged rentBasis=basket rather than dropped. Tax assumes local tax residency, single filer, no deductions. Estimates; not a quote and not tax advice.
      parameters:
      - name: income
        in: query
        required: true
        description: Monthly income in USD. Required - the tool is a subtraction.
        schema:
          type: number
          exclusiveMinimum: 0
      - name: sort
        in: query
        required: false
        description: Ranking. Default total.
        schema:
          type: string
          enum:
          - total
          - remaining
          - rent
          - tax
          - share
          default: total
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2; echoes that country's row and rank as focus.
        schema:
          type: string
      - name: maxPctOfIncome
        in: query
        required: false
        description: Keep only countries whose total is at or below this share of income (%).
        schema:
          type: number
          exclusiveMinimum: 0
      responses:
        '200':
          description: Countries ranked, each with its four cost lines, total, remainder and rent basis.
        '400':
          description: Missing or malformed parameter (no income, non-numeric value, bad sort).
        '422':
          description: Unknown country code.
      tags:
      - Total Cost.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/