{"openapi":"3.1.0","info":{"title":"GWIX API","version":"1.0.0","description":"Curated, integrated labor-market data with a source and citation on every result: advertised pay and its trend, hiring demand, companies, occupations and places, mapped to one taxonomy.\n\n**Start here:** [quickstart](/docs) · [try every endpoint in the API Explorer](/explore) · [guides](/docs/guides) · [pricing](https://gwix.ai/pricing) · [llms.txt for agents](/llms.txt) · [MCP server](https://gwix.ai/mcp)\n\n**Authentication:** send `Authorization: Bearer <your API key>`. Keys are created in the [console](/console); a free account starts with $250 in credits.\n\n**Credits:** every response shows the credits it used (`X-Credits-Charged`) and your balance (`X-Credits-Remaining`). Calls that return no data are free."},"servers":[{"url":"https://api.gwix.ai","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Statistics","description":"Advertised pay and hiring demand by occupation, role, company, industry and place."},{"name":"Lookups","description":"Turn plain-language names into GWIX IDs."},{"name":"Reference","description":"What an ID means, and maps between classifications."},{"name":"Discovery","description":"Data status, periods and the dimensions you can filter by."},{"name":"Service","description":"Service health."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your GWIX API key (create one in the console) or an OAuth access token."}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"Overall status; degraded if any check failed"},"checks":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Per-dependency probe results"},"time":{"type":"string","format":"date-time","description":"Server timestamp"}},"required":["status","checks","time"],"example":{"status":"ok","checks":{"gwix":true},"time":"2026-08-17T12:00:00.000Z"}},"StatusResponse":{"type":"object","properties":{"status":{"type":"string","enum":["operational","degraded"]},"api_version":{"type":"string"},"release":{"type":["string","null"],"description":"Live data release (e.g. 2026-W43); null until the first release is published."},"last_complete_week":{"type":["string","null"],"description":"Sunday ending the last complete week used by statistics."},"degraded_endpoints":{"type":"array","items":{"type":"string"}},"datasets":{"type":"array","items":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"last_complete_week":{"type":"string"},"status":{"type":"string","enum":["current","delayed","paused"]}},"required":["countries"]}}},"required":["status","api_version","release","last_complete_week","degraded_endpoints","datasets"]},"Ref":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"CompanyRef":{"allOf":[{"$ref":"#/components/schemas/Ref"},{"type":"object","properties":{"ticker":{"type":["string","null"]}}}]},"GeoLevel":{"type":"string","enum":["postal","city","metro","state","country"]},"LocationRef":{"allOf":[{"$ref":"#/components/schemas/Ref"},{"type":"object","properties":{"geo_level":{"$ref":"#/components/schemas/GeoLevel"}}}]},"PostingsRow":{"type":"object","properties":{"period_label":{"type":"string"},"period_start":{"type":"string"},"period_end":{"type":"string"},"country":{"type":"string"},"company":{"$ref":"#/components/schemas/CompanyRef"},"parent_company":{"$ref":"#/components/schemas/CompanyRef"},"location":{"$ref":"#/components/schemas/LocationRef"},"industry":{"$ref":"#/components/schemas/Ref"},"role":{"$ref":"#/components/schemas/Ref"},"job_family":{"$ref":"#/components/schemas/Ref"},"sub_job_family":{"$ref":"#/components/schemas/Ref"},"job_level":{"$ref":"#/components/schemas/Ref"},"soc_occupation":{"allOf":[{"$ref":"#/components/schemas/Ref"},{"type":"object","properties":{"soc_code":{"type":"string"}},"required":["soc_code"]}],"description":"With soc_id or occupation_code: the SOC 2018 detailed occupation."},"matched_from":{"type":"array","items":{"type":"object","properties":{"occupation_code":{"type":"string"},"title":{"type":"string"},"match_type":{"type":"string","enum":["exact","partial"]}},"required":["occupation_code","match_type"]},"description":"With occupation_code: the codes sent that map to this row's SOC occupation."},"coverage_status":{"type":"string","enum":["covered","not_covered"]},"new_postings":{"type":["integer","null"]},"prior_new_postings":{"type":["integer","null"]},"change_pct":{"type":["number","null"]},"change_null_reason":{"type":["string","null"],"enum":["below_minimum","not_covered","no_prior_period"]}},"required":["period_label","period_start","period_end","country","coverage_status","new_postings"]},"CreditBreakdown":{"type":"object","properties":{"charged":{"type":"integer"},"by_class":{"type":"array","items":{"type":"object","properties":{"class":{"type":"string"},"units":{"type":"integer"},"credits_per_unit":{"type":"integer"},"credits":{"type":"integer"}},"required":["class","units","credits_per_unit","credits"]}}},"required":["charged","by_class"]},"Meta":{"type":"object","properties":{"request_id":{"type":"string"},"resolved":{"type":"array","items":{"type":"object","properties":{"parameter":{"type":"string"},"input":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}},"required":["parameter","input","id","name"]}},"units":{"type":"string"},"currency_basis":{"type":"string"},"period_definition":{"type":"string"},"geo_level":{"$ref":"#/components/schemas/GeoLevel"},"industry_level":{"type":"number","enum":[4]},"zero_rows_omitted":{"type":"integer"},"ownership_basis":{"type":"string","enum":["current"]},"provenance":{"type":"object","properties":{"datasets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"last_complete_week":{"type":"string"}},"required":["last_complete_week"]}},"data_release":{"type":"string"},"computed_at":{"type":"string"}},"required":["datasets","data_release","computed_at"]},"citation":{"type":"object","properties":{"text":{"type":"string"},"url":{"type":"string"}},"required":["text","url"]},"credits":{"$ref":"#/components/schemas/CreditBreakdown"}},"required":["request_id"]},"Paging":{"type":"object","properties":{"next_cursor":{"type":["string","null"]},"total_rows":{"type":"integer"}},"required":["next_cursor","total_rows"]},"PostingsResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/PostingsRow"}},"meta":{"$ref":"#/components/schemas/Meta"},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["rows","meta","paging"]},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"retry_with":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"parameter":{"type":"string"},"message":{"type":"string"}},"required":["parameter","message"]}}},"required":["type","title","status"]},"PercentileSet":{"type":"object","properties":{"p10":{"type":["number","null"]},"p25":{"type":["number","null"]},"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]}}},"MarketBlock":{"type":"object","properties":{"scope":{"type":"string","enum":["national","industry","local","local_industry"]},"filters":{"type":"object","additionalProperties":{"type":["string","null"]}},"industry_level":{"type":"number","enum":[4]},"ads_with_pay":{"type":["integer","null"]},"percentiles":{"$ref":"#/components/schemas/PercentileSet"},"gap_pct":{"$ref":"#/components/schemas/PercentileSet"},"market_change_pct":{"$ref":"#/components/schemas/PercentileSet"},"growth_gap_pp":{"$ref":"#/components/schemas/PercentileSet"}},"required":["scope","filters","ads_with_pay","percentiles","gap_pct"]},"PayRow":{"type":"object","properties":{"period_label":{"type":"string"},"period_start":{"type":"string"},"period_end":{"type":"string"},"country":{"type":"string"},"company":{"$ref":"#/components/schemas/CompanyRef"},"parent_company":{"$ref":"#/components/schemas/CompanyRef"},"location":{"$ref":"#/components/schemas/LocationRef"},"industry":{"$ref":"#/components/schemas/Ref"},"role":{"$ref":"#/components/schemas/Ref"},"job_family":{"$ref":"#/components/schemas/Ref"},"sub_job_family":{"$ref":"#/components/schemas/Ref"},"job_level":{"$ref":"#/components/schemas/Ref"},"soc_occupation":{"allOf":[{"$ref":"#/components/schemas/Ref"},{"type":"object","properties":{"soc_code":{"type":"string"}},"required":["soc_code"]}],"description":"With soc_id or occupation_code: the SOC 2018 detailed occupation."},"matched_from":{"type":"array","items":{"type":"object","properties":{"occupation_code":{"type":"string"},"title":{"type":"string"},"match_type":{"type":"string","enum":["exact","partial"]}},"required":["occupation_code","match_type"]},"description":"With occupation_code: the codes sent that map to this row's SOC occupation."},"coverage_status":{"type":"string","enum":["covered","not_covered"]},"pay_unit":{"type":"string","enum":["annual","hourly"]},"currency":{"type":["string","null"],"description":"ISO 4217 currency of the percentiles: USD, or the country's currency with currency=local."},"fx_rate":{"type":"number","description":"Units of the country's currency per USD for the period (average of its weekly rates)."},"ads_with_pay":{"type":["integer","null"]},"percentiles":{"$ref":"#/components/schemas/PercentileSet"},"suppressed":{"type":"array","items":{"type":"object","properties":{"percentile":{"type":"string","enum":["p10","p25","p50","p75","p90"]},"reason":{"type":"string","enum":["below_minimum","not_covered","failed_quality_check"]}},"required":["percentile","reason"]}},"prior_ads_with_pay":{"type":["integer","null"]},"prior_percentiles":{"$ref":"#/components/schemas/PercentileSet"},"change_pct":{"$ref":"#/components/schemas/PercentileSet"},"market":{"type":"array","items":{"$ref":"#/components/schemas/MarketBlock"}}},"required":["period_label","period_start","period_end","country","coverage_status","pay_unit","currency","ads_with_pay","percentiles","suppressed"]},"PayResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/PayRow"}},"meta":{"$ref":"#/components/schemas/Meta"},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["rows","meta","paging"]},"LookupResponse":{"type":"object","properties":{"status":{"type":"string","enum":["matched","no_match","needs_disambiguation"]}},"required":["status"]},"DimensionValueDetail":{"type":"object","properties":{"dimension":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","retired"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["dimension","id","name","status","meta"]},"CrosswalkResponse":{"type":"object","properties":{"from":{"type":"object","properties":{"system":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"required":["system","code"]},"matches":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"match_type":{"type":"string","enum":["exact","broader","narrower","partial"]},"id":{"type":["string","null"]},"has_data":{"type":"boolean"},"via":{"type":"object","properties":{"system":{"type":"string"},"code":{"type":"string"}},"required":["system","code"]},"share_of_soc_ads":{"type":"number"},"ads":{"type":"integer"}},"required":["system","code","name","match_type"]}},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}},"required":["from","matches","meta"]},"DimensionCatalog":{"type":"object","properties":{"dimensions":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"id_field":{"type":"string"},"id_format":{"type":"string"}},"required":["dimension","id_field","id_format"]}}},"required":["dimensions"]},"FxRatesResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"period_type":{"type":"string","enum":["week","month","quarter","year"]},"period_label":{"type":["string","null"]},"period_start":{"type":"string"},"period_end":{"type":["string","null"]},"units_per_usd":{"type":"number","description":"Units of the currency per USD (the row fx_rate on /v1/pay)."},"usd_per_unit":{"type":"number"},"weeks_rated":{"type":["integer","null"]},"first_rate_month":{"type":["string","null"]},"last_rate_month":{"type":["string","null"]}},"required":["currency","period_type","period_label","period_start","period_end","units_per_usd","usd_per_unit","weeks_rated","first_rate_month","last_rate_month"]}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"rate_basis":{"type":"string"}},"required":["request_id","rate_basis"]}},"required":["rows","meta"]},"PeriodsResponse":{"type":"object","properties":{"last_complete_week":{"type":["string","null"]},"data_release":{"type":"string"},"periods":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"type":{"type":"string","enum":["week","month","quarter","year"]},"start":{"type":"string"},"end":{"type":"string"}},"required":["label","type","start","end"]}}},"required":["last_complete_week","periods"]}},"parameters":{}},"paths":{"/healthz":{"get":{"tags":["Service"],"summary":"Service health check","description":"Liveness/readiness probe. Runs each registered dependency check.","responses":{"200":{"description":"Service responded (inspect `status`/`checks` for dependency health)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/status":{"get":{"operationId":"get_status","tags":["Discovery"],"summary":"Data freshness","description":"Live release, last complete week and per-country coverage status. No release until the first build lands. Public and free.","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"required":false,"name":"country","in":"query"}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}}}}},"/v1/postings":{"get":{"operationId":"get_postings","tags":["Statistics"],"summary":"Ad volume and its trend","description":"Ads first posted per period, one row per period per filter value, from pre-built slices. Uses credits; X-Credits-Charged and X-Credits-Remaining show what was used.","parameters":[{"schema":{"type":"string","description":"Comma-separated brand-level company IDs (cmp_…). One row set per value."},"required":false,"name":"company_id","in":"query"},{"schema":{"type":"string","description":"Ultimate parent company ID; all its brands as one group (current ownership)."},"required":false,"name":"parent_company_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated country (US), state (US-CO) or metro (mtr_…) IDs. One row set per value."},"required":false,"name":"location_id","in":"query"},{"schema":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country. Required unless location_id is sent."},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","description":"Comma-separated 4-digit NAICS industry groups."},"required":false,"name":"industry_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated role IDs. Not pre-computed with company_id, parent_company_id or ticker (501)."},"required":false,"name":"role_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated job family IDs."},"required":false,"name":"job_family_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated sub-job family IDs."},"required":false,"name":"sub_job_family_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated job level IDs. Absent = all levels."},"required":false,"name":"job_level_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated SOC 2018 occupation IDs (soc_15-1252). Geography and job level only: not with company, parent company, ticker or industry (501)."},"required":false,"name":"soc_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated occupation codes as <system>:<code>: soc_2018:15-1252, soc_2010:15-1132, onet_soc:15-1252.00, isco_08:2512, esco:2512.4 (short system names soc, soc2010, onet, isco also accepted; a bare 15-1252 is SOC 2018). Each resolves to the SOC 2018 occupations it maps to: one row set per SOC, with matched_from and meta.occupation_codes."},"required":false,"name":"occupation_code","in":"query"},{"schema":{"type":"string","enum":["week","month","quarter","year"],"description":"Period type (default month)."},"required":false,"name":"interval","in":"query"},{"schema":{"type":"string","description":"First period label (2025-01, 2025-Q2, 2025, 2025-W14). Default: the latest complete period."},"required":false,"name":"start_period","in":"query"},{"schema":{"type":"string","description":"Last period label. Default: the latest complete period."},"required":false,"name":"end_period","in":"query"},{"schema":{"type":"string","enum":["previous","12_month"]},"required":false,"name":"compare","in":"query"},{"schema":{"type":"string","description":"Only the live release is served; another release returns 501."},"required":false,"name":"data_release","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from paging.next_cursor."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Rows per page, 1 to 1000 (default 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Stock ticker (MAR, or XNAS:MAR): the listed company's whole group, current ownership. Add country when a ticker is used in more than one country."},"required":false,"name":"ticker","in":"query"},{"schema":{"type":"string","description":"brand: with parent_company_id or ticker, one row set per brand with ads (zero brand-periods omitted, counted in meta.zero_rows_omitted)."},"required":false,"name":"split","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"weeks","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"periods","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"start_date","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use company_id."},"required":false,"name":"company","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use location_id."},"required":false,"name":"location","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use role_id."},"required":false,"name":"title","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use job_family_id."},"required":false,"name":"job_family","in":"query"}],"responses":{"200":{"description":"Ad counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostingsResponse"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough credits (payment challenge).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed (e.g. agent identification required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parameters valid individually but not together, unknown ID, or period outside the release.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Not pre-computed, or a feature not available yet.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No data release is live.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/pay":{"get":{"operationId":"get_pay","tags":["Statistics"],"summary":"Advertised pay and its trend","description":"Advertised pay percentiles in USD (default) or each country's own currency (currency=local) from pre-built slices; percentiles below their minimum count are null and listed in suppressed. Hourly = annual ÷ 2,080.","parameters":[{"schema":{"type":"string","description":"Comma-separated brand-level company IDs (cmp_…). One row set per value."},"required":false,"name":"company_id","in":"query"},{"schema":{"type":"string","description":"Ultimate parent company ID; all its brands as one group (current ownership)."},"required":false,"name":"parent_company_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated country (US), state (US-CO) or metro (mtr_…) IDs. One row set per value."},"required":false,"name":"location_id","in":"query"},{"schema":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country. Required unless location_id is sent."},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","description":"Comma-separated 4-digit NAICS industry groups."},"required":false,"name":"industry_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated role IDs. Not pre-computed with company_id, parent_company_id or ticker (501)."},"required":false,"name":"role_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated job family IDs."},"required":false,"name":"job_family_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated sub-job family IDs."},"required":false,"name":"sub_job_family_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated job level IDs. Absent = all levels."},"required":false,"name":"job_level_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated SOC 2018 occupation IDs (soc_15-1252). Geography and job level only: not with company, parent company, ticker or industry (501)."},"required":false,"name":"soc_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated occupation codes as <system>:<code>: soc_2018:15-1252, soc_2010:15-1132, onet_soc:15-1252.00, isco_08:2512, esco:2512.4 (short system names soc, soc2010, onet, isco also accepted; a bare 15-1252 is SOC 2018). Each resolves to the SOC 2018 occupations it maps to: one row set per SOC, with matched_from and meta.occupation_codes."},"required":false,"name":"occupation_code","in":"query"},{"schema":{"type":"string","enum":["week","month","quarter","year"],"description":"Period type (default month)."},"required":false,"name":"interval","in":"query"},{"schema":{"type":"string","description":"First period label (2025-01, 2025-Q2, 2025, 2025-W14). Default: the latest complete period."},"required":false,"name":"start_period","in":"query"},{"schema":{"type":"string","description":"Last period label. Default: the latest complete period."},"required":false,"name":"end_period","in":"query"},{"schema":{"type":"string","enum":["previous","12_month"]},"required":false,"name":"compare","in":"query"},{"schema":{"type":"string","description":"Only the live release is served; another release returns 501."},"required":false,"name":"data_release","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from paging.next_cursor."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Rows per page, 1 to 1000 (default 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Stock ticker (MAR, or XNAS:MAR): the listed company's whole group, current ownership. Add country when a ticker is used in more than one country."},"required":false,"name":"ticker","in":"query"},{"schema":{"type":"string","description":"brand: with parent_company_id or ticker, one row set per brand with ads (zero brand-periods omitted, counted in meta.zero_rows_omitted)."},"required":false,"name":"split","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"weeks","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"periods","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"start_date","in":"query"},{"schema":{"type":"string","description":"Not pre-computed yet (501)."},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use company_id."},"required":false,"name":"company","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use location_id."},"required":false,"name":"location","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use role_id."},"required":false,"name":"title","in":"query"},{"schema":{"type":"string","description":"Plain text: not available yet (501); use job_family_id."},"required":false,"name":"job_family","in":"query"},{"schema":{"type":"string","enum":["annual","hourly"]},"required":false,"name":"pay_unit","in":"query"},{"schema":{"type":"string","enum":["USD","local"],"description":"USD (default) or local: each country's own currency (row currency). Local values exclude exchange-rate effects; use them for trends within a country."},"required":false,"name":"currency","in":"query"},{"schema":{"type":"string","description":"Comma-separated subset of p10,p25,p50,p75,p90 (default all)."},"required":false,"name":"percentiles","in":"query"},{"schema":{"type":"string","description":"Comma-separated markets to compare with: national, industry, local, local_industry. Needs an occupation (role_id, sub_job_family_id, job_family_id, soc_id or occupation_code). Industry markets are monthly and longer, and not for SOC occupations."},"required":false,"name":"benchmark","in":"query"},{"schema":{"type":"string","description":"4-digit NAICS for the industry markets. Default: the subject's own industry."},"required":false,"name":"benchmark_industry_id","in":"query"}],"responses":{"200":{"description":"Pay percentiles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayResponse"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough credits (payment challenge).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed (e.g. agent identification required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parameters valid individually but not together, unknown ID, or period outside the release.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Not pre-computed, or a feature not available yet.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No data release is live.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/lookup/{type}":{"get":{"operationId":"lookup","tags":["Lookups"],"summary":"Resolve plain language to a standardized ID","description":"Exact (case-insensitive) name match against the live release's reference table for location, company, job_family and sub_job_family; industry from company_id. Only matches use credits; needs_disambiguation and no_match free. type=title returns 501 until the matcher service is connected.","parameters":[{"schema":{"type":"string","enum":["title","company","industry","location","job_family","sub_job_family"]},"required":true,"name":"type","in":"path"},{"schema":{"type":"string","description":"Name to match (2 to 200 characters)."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"ISO-2 country filter."},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","description":"Location: city/metro name."},"required":false,"name":"city","in":"query"},{"schema":{"type":"string","description":"Location: state name or code."},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","description":"Sub-job family: parent job family."},"required":false,"name":"job_family_id","in":"query"},{"schema":{"type":"string","description":"Location: postal code; resolves to the metro (else state, else country) most of its ads are in."},"required":false,"name":"postcode","in":"query"},{"schema":{"type":"string","description":"Company: stock ticker (MAR, or XNAS:MAR)."},"required":false,"name":"ticker","in":"query"},{"schema":{"type":"string","description":"Industry: the company whose industry to return."},"required":false,"name":"company_id","in":"query"},{"schema":{"type":"string","description":"1 to 10 (default 5)."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"matched, needs_disambiguation or no_match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough credits (payment challenge).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed (e.g. agent identification required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parameters valid individually but not together, unknown ID, or period outside the release.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Not pre-computed, or a feature not available yet.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No data release is live.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/dimensions/{dimension}/{id}":{"get":{"operationId":"describe_dimension_value","tags":["Reference"],"summary":"Describe an ID","description":"Name, parents and attributes of an ID in the live release. classifications=soc_2018 adds a role's SOC 2018 occupation.","parameters":[{"schema":{"type":"string","enum":["role","sub_job_family","job_family","soc_occupation","job_level","company","industry","location"]},"required":true,"name":"dimension","in":"path"},{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"soc_2018 (roles only at launch): add the role's SOC 2018 occupation."},"required":false,"name":"classifications","in":"query"}],"responses":{"200":{"description":"Description.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DimensionValueDetail"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough credits (payment challenge).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed (e.g. agent identification required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such value.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parameters valid individually but not together, unknown ID, or period outside the release.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Not pre-computed, or a feature not available yet.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No data release is live.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/taxonomy/crosswalk":{"get":{"operationId":"crosswalk","tags":["Reference"],"summary":"Map a code to other classifications","description":"Maps an occupation code (soc_2018, soc_2010, onet_soc, isco_08, esco) or a GWIX role to SOC 2018 detailed occupations and to the GWIX roles their ads fall in. soc_2018 matches carry id (soc_id for /v1/postings and /v1/pay). Each match states its type: exact, broader, narrower or partial. Unknown codes 404.","parameters":[{"schema":{"type":"string","enum":["soc_2018","soc_2010","onet_soc","isco_08","esco","gwix_role"],"description":"System of code (aliases soc, soc2010, onet, isco accepted)."},"required":true,"name":"from_system","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Code in from_system, e.g. 2512 (isco_08), 2512.4 (esco), 15-1252.00 (onet_soc), 15-1132 (soc_2010), 15-1252 (soc_2018), rol_… (gwix_role)."},"required":true,"name":"code","in":"query"},{"schema":{"type":"string","description":"Comma-separated targets: soc_2018, gwix_role. Others return 422 until their crosswalks are built."},"required":true,"name":"to_system","in":"query"},{"schema":{"type":"string","description":"gwix_role matches per SOC occupation, largest first, 1 to 500 (default 25)."},"required":false,"name":"roles_limit","in":"query"}],"responses":{"200":{"description":"Matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrosswalkResponse"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough credits (payment challenge).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed (e.g. agent identification required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Code not in the crosswalk.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parameters valid individually but not together, unknown ID, or period outside the release.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Not pre-computed, or a feature not available yet.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No data release is live.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/dimensions":{"get":{"operationId":"list_dimensions","tags":["Reference"],"summary":"Dimension catalog","description":"Dimensions used as filters, their ID formats and lookups. Public and free.","responses":{"200":{"description":"Dimension catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DimensionCatalog"}}}}}}},"/v1/fx-rates":{"get":{"operationId":"list_fx_rates","tags":["Reference"],"summary":"Exchange rates GWIX used","description":"The exchange rates the live release used to convert pay between each country's currency and USD, per currency and period, so you can map GWIX figures to your own rates. Send currencies, or countries (their currency in the release). Public and free.","parameters":[{"schema":{"type":"string","description":"Comma-separated ISO 4217 codes (e.g. EUR,JPY)."},"required":false,"name":"currency","in":"query"},{"schema":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 countries; returns their currency's rates, with the countries listed."},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","enum":["week","month","quarter","year"],"description":"Period type (default month)."},"required":false,"name":"interval","in":"query"},{"schema":{"type":"string","description":"First period label. Default: the latest complete period."},"required":false,"name":"start_period","in":"query"},{"schema":{"type":"string","description":"Last period label. Default: the latest complete period."},"required":false,"name":"end_period","in":"query"}],"responses":{"200":{"description":"Rates per currency and period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FxRatesResponse"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Period outside the release, unknown country, or too many rows.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No data release is live.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/periods":{"get":{"operationId":"list_periods","tags":["Reference"],"summary":"Which dates make up each period","description":"Weeks, 4-week months, 13-week quarters and 52-week years lying wholly inside [from, to] (default: the live release's window). Public and free.","parameters":[{"schema":{"type":"string","enum":["week","month","quarter","year"]},"required":true,"name":"type","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Periods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeriodsResponse"}}}},"400":{"description":"Malformed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No release and no explicit range.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{}}