FAQ¶
Common questions from developers. Something not covered here: write to communications@whereyouworkmatters.org.
Access¶
How do I get access? Use Get access on wywm.org, or write to communications@whereyouworkmatters.org with your name, organization and what you want to build.
Is there an API key?
Your code signs in with your username and password at POST /auth/login and
sends the token it gets back as Authorization: Bearer <token> (see the
Overview). The access token lasts 24
hours; the same response carries a refresh token, valid 90 days, to get a new
one without the password. Server-side apps that cannot sign in can be given an
app key by arrangement.
My token stopped working. Access tokens last 24 hours. Use the refresh token, or sign in again.
I get "Access denied" on wages, or on MCP. Your account is not set up for that data area or interface. Ask us to add it.
I'm getting HTTP 429. You have hit the per-minute rate limit. Back off and retry. If your use needs more, tell us.
Using the API¶
DSL, MCP or REST: which should I use?
Start with the DSL: one endpoint (POST /api/dsl) and readable
queries such as TITLECONVERT "registered nurse". Use MCP
(https://aonav.ai/mcp) to connect an AI agent; it exposes the same DSL as a
tool. REST is there for simple lookups and existing integrations.
Can I chain queries with | or ;?
No. Run each step as its own query and pass the result to the next.
Can I try queries without writing code? Yes: the developer console at wywm.org/console, with the same login.
A result looks wrong.
Send us the exact query and the response. For job-title matches,
SUBMIT TITLECONVERT records the right answer directly (see the
DSL reference).
The data¶
Where does the data come from? Employer ratings come from observed career outcomes: career-site profiles (about 12 million U.S. workers, mostly 2019–2024) and job-posting data. All wage data comes from surveys and other information collected directly by our partner, the Burning Glass Institute (BGI), from a base that taps into 65 million employee, job posting and other records. Companies cannot pay for a rating or opt out.
What does NA mean? Not enough data for that rating. It does not mean a poor employer.
How are occupations identified?
By the Department of Labor's O*NET taxonomy, grouped into occupation clusters.
TITLECONVERT turns a free-text job title into them; the
data dictionary lists the fields.
Changes¶
How stable is the API? It is in beta. Changes are announced in the Changelog, and we keep existing queries working wherever we can.