Geo-Parity Residency Tracker API

openapi: 3.2.0
info:
  title: Geo-Parity Residency Tracker 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: Residency Tracker
paths:
  /api/residency-tracker:
    post:
      operationId: trackResidency
      summary: Unified Schengen 90/180 + per-country tax residency + tax cost, from one…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - stays
              properties:
                stays:
                  type: array
                  items:
                    type: object
                    required:
                    - country
                    - entry
                    - exit
                    properties:
                      country:
                        type: string
                      entry:
                        type: string
                        format: date
                      exit:
                        type: string
                        format: date
                income:
                  type: number
                  description: optional gross annual USD — enables tax-cost projection
                referenceDate:
                  type: string
                  format: date
      responses:
        '200':
          description: schengen block, per-country risk (threshold/basis/safeDaysLeft/risk, Cyprus-60 secondary, US SPT, UK, taxProjection) and a summary
        '400':
          $ref: '#/components/responses/MissingParams'
        '422':
          $ref: '#/components/responses/InvalidInput'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Residency Tracker
components:
  responses:
    InvalidInput:
      description: Well-formed but invalid input; body includes a machine-readable code (e.g. UNKNOWN_TARGET) and message.
    MissingParams:
      description: Required parameters missing; body includes code, message, and a worked example.
    RateLimited:
      description: A ceiling was exceeded. Body is { ok:false, code, message, retryAfterSeconds } where code is RATE_LIMITED (per-minute burst — back off and retry within the minute) or QUOTA_EXCEEDED (the monthly allowance is spent; retrying will not help until it resets on the 1st). Honour Retry-After.
      headers:
        Retry-After:
          description: Seconds until the exceeded ceiling resets.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute for this caller (burst).
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in the current minute.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Minute window reset, epoch seconds.
          schema:
            type: integer
        X-Quota-Limit:
          description: Requests allowed this calendar month for this caller.
          schema:
            type: integer
        X-Quota-Remaining:
          description: Requests left this month.
          schema:
            type: integer
        X-Quota-Reset:
          description: Quota reset (1st of next month, UTC), epoch seconds.
          schema:
            type: integer
  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/