Geo-Parity Team Calendar.json API

openapi: 3.2.0
info:
  title: Geo-Parity Team Calendar.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: Team Calendar.json
paths:
  /api/team-calendar.json:
    get:
      operationId: planTeamCalendar
      summary: Shared working days and hours for a multi-country team
      description: Weekdays on which nobody in the team is on a public holiday, joined to the daily working-hour overlap across the members' time zones (evaluated on 15 January and 15 July so daylight saving is visible), and multiplied into conservative shared working hours per year. Members are ISO alpha-2 codes, each optionally `CC@IANA/Zone`; countries spanning several zones are flagged multiZone. Spine countries with no holiday calendar (IN, TH, MY, AE, SA) return 422 NO_DATA.
      parameters:
      - name: members
        in: query
        required: true
        schema:
          type: string
        description: Comma-separated ISO alpha-2 codes, two or more, each optionally CC@IANA/Zone (e.g. GB,JP,US@America/Chicago)
      - name: year
        in: query
        schema:
          type: number
        description: Calendar year; defaults to the first year in the holiday dataset
      - name: start
        in: query
        schema:
          type: number
        description: Default working-window start, minutes from midnight (540)
      - name: end
        in: query
        schema:
          type: number
        description: Default working-window end, minutes from midnight (1080)
      - name: hours
        in: query
        schema:
          type: string
        description: Per-member start-end overrides, semicolon-separated and aligned with members
      responses:
        '200':
          description: Members, days, winter/summer hours, sharedWorkingHoursPerYear, caveats and an attribution block
        '400':
          description: members missing (MISSING_PARAMS), fewer than two countries (TOO_FEW), or malformed hours/date (INVALID_HOURS, INVALID_DATE)
        '422':
          description: Unknown country or zone (UNKNOWN_COUNTRY, UNKNOWN_ZONE), or no holiday calendar for a member (NO_DATA)
      tags:
      - Team Calendar.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/