> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use issue taxonomy

> Choose Atlas domains and issue areas for search, discovery, and integrations.

## 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](/docs/taxonomy). For
exact schemas, use the
[API reference](/docs/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.

```bash theme={null}
curl "https://atlas.rebuildingus.org/api/issue-areas"
curl "https://atlas.rebuildingus.org/api/domains"
```

## Pick slugs from the user's intent

Start with the user's actual question, then choose the narrowest issue area that
still matches it.

| User intent                                      | Likely issue area                     |
| ------------------------------------------------ | ------------------------------------- |
| Tenant organizing, evictions, rent burden        | `housing_affordability`               |
| Bus service, transit advocacy, safer streets     | `public_transit`                      |
| Worker centers, wage theft, union drives         | `union_organizing`                    |
| Pollution, toxic sites, local environmental harm | `environmental_justice_and_pollution` |

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

```bash theme={null}
curl "https://atlas.rebuildingus.org/api/places/kansas-city,missouri/entities?issue_area=housing_affordability"
```

Use multiple values to widen the issue facet:

```bash theme={null}
curl "https://atlas.rebuildingus.org/api/places/kansas-city,missouri/entities?issue_area=housing_affordability&issue_area=union_organizing"
```

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

<CardGroup cols={2}>
  <Card title="Full taxonomy" icon="tags" href="/docs/taxonomy">
    Browse the human-readable issue areas and domains.
  </Card>

  <Card title="Research a place" icon="map" href="/docs/api/guides/places">
    Apply issue areas to a place-first workflow.
  </Card>
</CardGroup>