Skip to main content

​
Overview

Atlas uses a shared issue taxonomy so people, API clients, Scout, and MCP tools can talk about civic work with the same vocabulary. Use taxonomy APIs when you need to choose issue area slugs, display labels, or translate a user’s plain-language topic into API filters. For the human-readable taxonomy, see Issue areas and domains. For exact schemas, use the API reference.

​
Domains and issue areas

Domains are broad categories. Issue areas are the practical filters you will use most often in API requests. For example:
  • A domain can help a UI group related topics.
  • An issue area can filter actors, places, discovery runs, and coverage.
  • A label can appear in the interface.
  • A slug should be stored in code and API calls.
Use the API to fetch the current vocabulary instead of hard-coding a local copy.

​
Pick slugs from the user’s intent

Start with the user’s actual question, then choose the narrowest issue area that still matches it. When the intent spans more than one issue, use multiple issue areas rather than inventing a new label in your integration.

​
Filter with issue areas

Use multiple values to widen the issue facet:
Then combine with place, actor type, text, or source filters only when the result set needs more focus.

​
Use MCP for natural language mapping

When a user is working through an AI assistant, the MCP tool can map a phrase to Atlas issue slugs. Example prompt:
What Atlas categories relate to affordable childcare?
The assistant can call resolve_issue_areas, show candidate slugs, and then use the selected slug in a search or discovery workflow. This is usually better than asking the user to memorize taxonomy names.

​
Avoid taxonomy drift

Do not maintain a second taxonomy in an app, spreadsheet, or agent prompt. It will drift from Atlas and make filters inconsistent. Instead:
  • Fetch issue areas and domains from the API.
  • Store slugs, not labels.
  • Display labels from the API response.
  • Refresh cached taxonomy data when the integration starts or on a schedule.
  • Use the generated reference when you need exact field names.

​
Next steps

Full taxonomy

Browse the human-readable issue areas and domains.

Research a place

Apply issue areas to a place-first workflow.