---
title: "Apple Jobs location discovery"
method: GET
path: "/apple-jobs/locations"
tags: ["Apple Jobs"]
---

# Apple Jobs location discovery

`GET /apple-jobs/locations`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/apple-jobs/locations`
- Auth: API key in header `x-api-key`

Discovery endpoint for apple-jobs-search's `location` parameter, whose accepted values are a closed set Apple itself defines (its own `<slug>-<CODE>` location ids -- free-text location names are rejected). Apple exposes no bulk "list everything" option for this; the only lookup is a fuzzy search capped at 10 results per call covering four granularities (country, state/province, metro area, city) with no empty-input listing mode. With no `q`, this returns the full country-level value space (206 values, live-verified) as a static list -- the granularity apple-jobs-search's own examples use and nearly every caller needs. With `q` supplied, this instead looks up Apple's own location filter live so callers can discover state/metro/city-level values for finer filtering; results at those deeper levels may include more than one candidate and are ranked by Apple's own relevance, not alphabetically.

## Query parameters

- `q` string

## Headers

- `x-api-key` string, required

## Response `200`

OK

- ApplejobsLocationsResponseDoc
  - `code` integer
  - `data` ApplejobsLocationsResponse
    - `count` integer
    - `fetched_at` string
    - `locations` ApplejobsLocationRef[]
      - `code` string
      - `level` string: Level is "country", "state", "metro", or "city" -- see LocationsResponse's doc comment for why only "country" is enumerated by default.
      - `location` string
      - `name` string
    - `query` string: Query echoes the q parameter. Empty when the response is the default country-level enumeration (Scope == "country").
    - `scope` string: Scope is "country" for the default bulk country enumeration, or "search" when q was supplied and the response is a live pass-through of Apple's own location typeahead (which can return country, state, metro, or city-level matches).
    - `source_url` string
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `503`: Service Unavailable

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)