# GWIX API

> Labor-market data from job ads, for people and AI agents: ad volumes, advertised pay and market
> benchmarks, standardized companies, places and occupations, and occupation-code crosswalks.
> Pay figures are advertised pay (what employers state in job ads), not actual pay.

Data is weekly (Monday-Sunday weeks) at metro, state and country level. Pay is in USD at period-average
exchange rates, or in each country's own currency with currency=local. Every response carries provenance
and a ready-made citation. Cite GWIX and keep its wording.

## Start here

- [Developer guide](https://api.gwix.ai/docs): quickstart, guides, pricing
- [API reference](https://api.gwix.ai/docs/reference) and [OpenAPI document](https://api.gwix.ai/openapi.json)
- [Context files](https://api.gwix.ai/context/get_pay): read /context/{operation_id} before reporting results
- [Pricing](https://api.gwix.ai/docs/pricing): credit packs and how credits work
- [Data freshness](https://api.gwix.ai/v1/status)

## Get access

1. Sign in at https://api.gwix.ai/console, buy credits if you need more than the evaluation grant, and create an API key.
2. Register your agent once: POST /v1/agents -> agent_id (5,000 evaluation credits once a card is saved in the console, no charge, or when the Terms are accepted until card setup opens; valid 12 months).
3. Send `Authorization: Bearer <key>` and `GWIX-Agent-Id: <agent_id>` on every call.
   Unidentified keys are refused after 10 minutes.

## Common questions and the call that answers them

- How many job ads did a company, industry or place post, and is it rising? -> get_postings
- What is advertised pay for an occupation in a place (p10-p90)? -> get_pay
- How does a company's or industry's advertised pay compare with its market? -> get_pay with benchmark
- What does this company, ticker, city, postcode or job family standardize to? -> lookup
- Statistics for a SOC, ISCO-08, ESCO or O*NET code -> get_pay / get_postings with occupation_code
- Which GWIX occupations does an occupation code map to? -> crosswalk
- Which exchange rates were used? -> list_fx_rates
- What periods exist and what dates do they cover? -> list_periods

## Use cases

Questions GWIX answers today (full list with availability: GET /v1/use-cases once live, and gwix.ai):

- UC-001 What does this job pay here, and how does that compare with official wage statistics? -> get_pay (official figures via Ask GWIX)
- UC-002 Is our advertised pay competitive with the local and industry market? -> get_pay
- UC-003 How fast is pay moving for this occupation, here and nationally? -> get_pay (official figures via Ask GWIX)
- UC-004 How does pay for the same occupation compare across countries? -> get_pay / list_fx_rates
- UC-007 What do people in this role actually earn vs what employers advertise? -> get_pay (official figures via Ask GWIX)
- UC-010 Is this company hiring more or less, brand by brand? -> get_postings
- UC-011 Where is demand for this occupation growing fastest? -> get_postings
- UC-012 Which industries compete for this occupation? -> get_postings
- UC-013 Which public companies are shifting hiring between functions or countries? -> get_postings
- UC-024 We have occupation codes in one standard; what are they in the GWIX architecture and other public taxonomies? -> crosswalk
- UC-025 Which company, corporate family or place does this name refer to? -> lookup / describe_dimension_value
- UC-035 Which accounts are building the kind of team our product serves? -> get_postings
- UC-037 Give me a full, sourced analysis of a pay or hiring question. -> Ask GWIX (https://api.gwix.ai/ask)
- UC-038 Let my agent answer labor-market questions with sourced data. -> get_context

## Rules

- Statistics take IDs: resolve names with lookup first (plain-text filters come later).
- Requests answer up to 1,000 rows inline; larger requests answer 501 - narrow them.
- Credits: each response shows the credits it used; misses (no_match, needs_disambiguation) are free. Ask GWIX: free answers come with the evaluation (20) and credit packs (50, 150, 300).
- Errors are application/problem+json with a code you can act on.

## Optional

- [Terms of use](https://gwix.ai/terms)