API reference · Lookups

Resolve occupations and classification codes

GEThttps://trawle.com/v1/occupations

Deterministic title aliases, names, slugs or SOC/ISCO code prefixes. Candidates include family slugs usable in JobQuery.families. Occupation slugs and codes are not role filters; resolve role slugs with GET /v1/roles. Unknown input returns an empty list.

Authentication

Header x-api-key: Read-only API key from https://trawle.com/account#api-keys. 1,000 requests per daily window. Anonymous requests are also supported with a per-IP limit.

Parameters

Query

qstringrequired
Job title, occupation or classification code.
Limits
1 to 100 characters
Example
senior frontend developer
limitintegeroptional
Default
8
Limits
1 to 20

Responses

200Ranked occupation candidates.OccupationLookup

itemsarray<object> · OccupationMatchrequired
6 propertiesper item
- slugstringrequired
- namestringrequired
- familyobjectrequired
  2 properties
  slugstringrequired
  namestringrequired
- socCodestringrequired
  O*NET-SOC 2019 code (classification metadata, not a JobQuery role slug).
  Example
  15-1252.00
- iscoCodestringrequired
  ISCO-08 unit-group code.
  Example
  2512
- matchstringrequired
  How the input matched: deterministic title alias or a name/code prefix candidate. Confirm ambiguous candidates with the person.
  One of
  exactphraseprefix

400Invalid request: see error.issues and error.hint.Error

errorobjectrequired
4 properties
- codestringrequired
  Machine-readable: invalid_request, not_found, forbidden, rate_limited, internal.
  Example
  invalid_request
- messagestringrequired
  Example
  places: expected an array of GeoNames ids
- hintstringoptional
  What to do next, e.g. which lookup to call first.
  Example
  Resolve place names to ids with GET /v1/places?q=
- issuesarray<object>optional
  Validation problems, one per invalid field.
  2 propertiesper item
  pathstringrequired
  messagestringrequired

401Invalid, expired or revoked API key.Error

errorobjectrequired
4 properties
- codestringrequired
  Machine-readable: invalid_request, not_found, forbidden, rate_limited, internal.
  Example
  invalid_request
- messagestringrequired
  Example
  places: expected an array of GeoNames ids
- hintstringoptional
  What to do next, e.g. which lookup to call first.
  Example
  Resolve place names to ids with GET /v1/places?q=
- issuesarray<object>optional
  Validation problems, one per invalid field.
  2 propertiesper item
  pathstringrequired
  messagestringrequired

429Rate limit reached. Respect Retry-After and cache results.Error

errorobjectrequired
4 properties
- codestringrequired
  Machine-readable: invalid_request, not_found, forbidden, rate_limited, internal.
  Example
  invalid_request
- messagestringrequired
  Example
  places: expected an array of GeoNames ids
- hintstringoptional
  What to do next, e.g. which lookup to call first.
  Example
  Resolve place names to ids with GET /v1/places?q=
- issuesarray<object>optional
  Validation problems, one per invalid field.
  2 propertiesper item
  pathstringrequired
  messagestringrequired

PreviousList job families for the families filter NextFind skills by prefix

GET /v1/occupations

curl "https://trawle.com/v1/occupations?q=senior%20frontend%20developer" \
  -H "x-api-key: $TRAWLE_API_KEY"

Response

{
  "items": [
    {
      "slug": "string",
      "name": "string",
      "family": {
        "slug": "string",
        "name": "string"
      },
      "socCode": "15-1252.00",
      "iscoCode": "2512",
      "match": "exact"
    }
  ]
}