# crosswalk

> Map a code to other classifications

**Call:** `GET /v1/taxonomy/crosswalk`  
**Price:** Uses credits (see each response's `X-Credits-Charged`)  
**Available:** soft launch  
**Contract:** https://api.gwix.ai/docs/reference

## What it's for

Map a code between GWIX and external classifications (O*NET-SOC, SOC 2018, SOC 2010, ISCO-08, ESCO, NAICS), in either direction.

## Use it when

- A user or system supplies an occupation or industry code instead of a title.
- Showing which GWIX roles make up a SOC occupation before choosing between soc_id and role_id.

## Inputs

| Name | In | Type | Required | Meaning |
|---|---|---|---|---|
| `from_system` | query | string: gwix_role | onet_soc | soc_2018 | soc_2010 | isco_08 | esco | naics | isic_4 | yes |  |
| `code` | query | string | yes |  |
| `to_system` | query | list of string: gwix_role | onet_soc | soc_2018 | soc_2010 | isco_08 | esco | naics | isic_4 | yes |  |
| `roles_limit` | query | integer |  | gwix_role matches per SOC occupation, largest first (default 25). |

Headers: `GWIX-Agent-Id`, `GWIX-On-Behalf-Of`.

## What comes back

`from`, `matches`, `meta`.

## Rules

**Identify your agent.** Send `GWIX-Agent-Id` on every call (register once with `register_agent`). Unidentified keys get reduced limits and are refused after 10 minutes.

## Notes

- Each match states `exact`, `broader`, `narrower` or `partial`.
- At launch, targets are `soc_2018` and `gwix_role`. A `soc_2018` match's `id` is the `soc_id` for get_postings and get_pay; `has_data: false` means no ads in this release.
- To get statistics for a code directly, skip this call and send `occupation_code` to get_postings or get_pay.
- `isic_4` and `nace_2` are reserved and return 422 until their crosswalks are built.

## When it doesn't work

| Status | What to do |
|---|---|
| 400 | Fix the request; `invalid_params` names each bad parameter. |
| 401 | Send a valid API key (`Authorization: Bearer ...`). |
| 402 | Not enough credits. The body lists packs and plans that would cover it. |
| 403 | Not allowed for this key or tier, a cap is reached, or the agent is unidentified; read `type` and `detail`. |
| 404 | No such ID. Use `lookup` or `list_dimension_values` to find valid IDs. |
| 429 | Rate or concurrency limit. Wait `Retry-After` seconds. |

## Next steps

[`get_pay`](/context/get_pay) · [`get_postings`](/context/get_postings)

## Example response

```json
{
  "from": {
    "system": "isco_08",
    "code": "2512",
    "name": "Software developers"
  },
  "matches": [
    {
      "system": "soc_2018",
      "code": "15-1252",
      "name": "Software Developers",
      "match_type": "exact",
      "id": "soc_15-1252",
      "has_data": true
    },
    {
      "system": "gwix_role",
      "code": "rol_software_developer",
      "name": "Software Developer",
      "match_type": "narrower",
      "id": "rol_software_developer",
      "has_data": true,
      "via": {
        "system": "soc_2018",
        "code": "15-1252"
      },
      "share_of_soc_ads": 0.41,
      "ads": 302126
    }
  ],
  "meta": {
    "request_id": "gwx_req_77ef"
  }
}
```