Sites, information types, and services
Public Where You Work Matters sites, developer docs for this API, the information this service publishes (named as DSL uses them), and how the service itself is accessed.
Public sites
why.whereyouworkmatters.org
Worker-facing explorer: find employers that rate well for a given occupation. Opens in a new tab.
Corporate sitewww.whereyouworkmatters.org
The List for companies: overall and occupation-level ratings, the three job-quality archetypes, and methodology for employers. Opens in a new tab.
Developer resources
API reference and data dictionary
Field-level syntax and the schema those calls read. Same gate as the rest of /api-docs. Not the public product sites above.
Information types
These are the published subjects. Filter and field names below are the DSL vocabulary (same meaning on REST). Insufficient badge evidence is — (null / NA), not a low score. Ranked means any non-NA badge (Platinum or Gold).
| Information type | What it is | DSL (typical) |
|---|---|---|
| Company | Assessed U.S. employer: canonical name, COMPANY_UID, INDUSTRY, place (COMPANY_CITY / COMPANY_STATE), and EVENT_TYPE (acquired, merged, rebranded, …). |
LIST COMPANIES · GET COMPANY · COMPANYCONVERT |
| Company badges | Job-quality ratings: OVERALL_BADGE plus three archetypes — BADGE_EARLY_CAREER, BADGE_GROWTH, BADGE_STABILITY. Values: Platinum, Gold, or —. |
LIST COMPANIES WHERE OVERALL_BADGE IS "Platinum" · COUNT COMPANY_BADGES GROUP BY ARCHETYPE |
| Occupation | O*NET occupation: ONET_CODE, title, JOB_LEVEL, education, and optional AI_FLAG (Raising the Bar, Shrinking Fields, Winners Pull Away, Lower Potential). |
LIST OCCUPATIONS · TITLECONVERT · GET AI_IMPACT FOR OCCUPATION |
| Occupation × company | How that employer does for a specific role: occupation badges plus hiring volume (ENTRY_POSTING_TIER / TOTAL_POSTING_TIER: high through none). |
LIST OCCUPATIONS FOR COMPANY · LIST OCCUPATION_BADGES |
| Occupation cluster | A neighborhood of related occupations (premium skills, job level). Resolve a title to a cluster, then list who hires in it. | TITLECONVERT … EXPAND CLUSTER · LIST CLUSTERS · LIST COMPANIES FOR CLUSTER |
| Wages | Pay for an occupation, optionally by metro size (MSA_SIZE Large or Small/Medium) and EXPERIENCE_LEVEL. |
GET WAGES FOR OCCUPATION WHERE ONET_CODE IS "…" |
| Hiring | Where and how much an employer posts, including metro (CBSA) and posting-volume quantile (HIRING_POSTINGS_QTILE). |
GET HIRING FOR COMPANY · LIST COMPANIES FOR CLUSTER … ORDER BY TOTAL_POSTINGS |
| Pathways | Next-step clusters: skill-adjacent (similar skills) and destination (where people actually move), optionally scoped to a company. | LIST SKILL_ADJACENT_CLUSTERS · LIST DESTINATION_CLUSTERS |
| Name / title convert | Turn a typed job title or company string into the canonical occupation or employer (and optional cluster). Record the user’s pick; do not re-run convert. | TITLECONVERT · TITLECONVERT … EXPAND CLUSTER · COMPANYCONVERT · SUBMIT TITLECONVERT |
Service overview
This host is one service. REST, DSL, and MCP read the same tables. DSL (POST /api/dsl) is the full language. REST is the path-based subset. MCP is one tool, aoi_dsl_query, speaking DSL over POST /mcp. Every data call needs a JWT (user / analyst / admin). Contractor apps use the published proxy with an API key; a session id is attribution, not a second login.
On this host: Console runs REST/DSL against live data, Admin is operators, Chat is Open WebUI grounded on MCP, and this page is home. POST /api/translate turns a sentence into DSL or REST — the Console NL tab is a debugger; conversation belongs in Chat. Career Check short-links create and resolve a compact career payload for partner tools; they are separate from the query APIs and under the same confidentiality terms. In Chat, HELP COMPANIES, HELP BADGES, HELP CONVERT, and HELP SCHEMA are the topic briefs.
Production and staging stay up together. GET /health, /api/version, and /changelog are the public record of what is running.