> ## Documentation Index > Fetch the complete documentation index at: https://docs.peakmetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # Look up locations > Returns locations from PeakMetrics' normalized location taxonomy. Use this endpoint to discover the numeric location `id` values you pass to the `locations.` filters on the mentions, timeline, distribution, and narratives endpoints. The taxonomy has six levels, from coarsest to finest: `region`, `subregion`, `country`, `state`, `county`, and `city`. `state` and `county` are United States only — mentions outside the US resolve to a country and, where the source is specific enough, a city. **Location ids are unique only within a level.** Each level is its own id space, so region `1`, country `1`, and city `1` are three different places. That is why `parent_id` must always be sent together with `parent_level`, and why mentions are filtered with a per-level parameter (`locations.country`, `locations.city`, and so on) rather than one combined parameter. At least one of `level`, `query`, or `parent_id` is required. Combine them to narrow the results — for example `?parent_id=10&parent_level=country&query=cal` returns the direct children of the United States whose names start with "cal". **Pagination** — every response is paged. `limit` defaults to 100 and may be up to 500; `offset` skips results. The `pagination` object reports `total` for the whole query and `hasMore`, so you can enumerate a level completely — all ~3,100 US counties, or the full city list — by walking `offset` forward. Results are ordered coarsest level first, then cities by population descending, and that order is stable, so a result cannot move between pages. **Coverage** — location resolution is best effort and coverage varies by channel. It is strong for news and partial for social, and mentions published more than 90 days before September 16, 2026 carry no normalized location at all. No boundary or geometry data is returned. ## OpenAPI ````yaml /api/api_docs.yaml get /locations openapi: 3.1.0 info: title: PeakMetrics API description: > The PeakMetrics API provides programmatic access to narrative intelligence data. Access millions of mentions across news, social media, and online platforms, enriched with custom AI-powered smart categories and over 50 metadata properties. The API enables you to identify, analyze, and act on emerging narratives in real-time. version: 2.0.0 servers: - url: https://api.peakmetrics.com description: Main (production) server security: - BearerAuth: [] tags: - name: Authorization - name: Workspaces - name: Folders - name: Channels - name: Locations description: > PeakMetrics resolves a normalized location on mentions across every channel, using a six-level taxonomy: `region`, `subregion`, `country`, `state`, `county`, and `city`. `state` and `county` are United States only. Look locations up with `GET /locations`, read a mention's resolved location from the `location` object on `GET /workspaces/{workspaceId}/mentions`, filter any of the mentions, timeline, distribution, or narratives endpoints with the `locations.` parameters, and break counts down with the matching `locations.` `group_by` values. - name: Custom Channels - name: Custom Enrichments description: > Custom enrichments let you push external context about mentions into PeakMetrics, attached to individual mentions and used alongside all other mention metadata across the platform. Once written, enrichment values feed into narrative analysis, workspace summaries, and notifications, and are available through the customer API and the MCP server. Your team manages its own custom enrichments through the API: create one with `POST /customEnrichments`, list them with `GET /customEnrichments`, rename one or replace its option list with `PUT /customEnrichments/{enrichmentId}`, retire one with `DELETE /customEnrichments/{enrichmentId}`, and push values for individual mentions with `PUT /mentions/customEnrichments`. paths: /locations: get: tags: - Locations summary: Look up locations description: > Returns locations from PeakMetrics' normalized location taxonomy. Use this endpoint to discover the numeric location `id` values you pass to the `locations.` filters on the mentions, timeline, distribution, and narratives endpoints. The taxonomy has six levels, from coarsest to finest: `region`, `subregion`, `country`, `state`, `county`, and `city`. `state` and `county` are United States only — mentions outside the US resolve to a country and, where the source is specific enough, a city. **Location ids are unique only within a level.** Each level is its own id space, so region `1`, country `1`, and city `1` are three different places. That is why `parent_id` must always be sent together with `parent_level`, and why mentions are filtered with a per-level parameter (`locations.country`, `locations.city`, and so on) rather than one combined parameter. At least one of `level`, `query`, or `parent_id` is required. Combine them to narrow the results — for example `?parent_id=10&parent_level=country&query=cal` returns the direct children of the United States whose names start with "cal". **Pagination** — every response is paged. `limit` defaults to 100 and may be up to 500; `offset` skips results. The `pagination` object reports `total` for the whole query and `hasMore`, so you can enumerate a level completely — all ~3,100 US counties, or the full city list — by walking `offset` forward. Results are ordered coarsest level first, then cities by population descending, and that order is stable, so a result cannot move between pages. **Coverage** — location resolution is best effort and coverage varies by channel. It is strong for news and partial for social, and mentions published more than 90 days before September 16, 2026 carry no normalized location at all. No boundary or geometry data is returned. parameters: - in: query name: level required: false schema: type: string enum: - region - subregion - country - state - county - city description: > Scope the results to a single level of the taxonomy. Cannot be combined with `parent_id`. At least one of `level`, `query`, or `parent_id` is required. example: state - in: query name: query required: false schema: type: string minLength: 2 description: > A case-insensitive **prefix** match on the location name — `cal` matches "California", but `ifornia` does not. Must be at least 2 characters. On its own, `query` searches all six levels. Combined with `level` or `parent_id`, it narrows those results instead. example: san fran - in: query name: parent_id required: false schema: type: integer description: > Return only the **direct** children of this location — never grandchildren. Requires `parent_level`, because ids are unique only within a level. Cannot be combined with `level`. At least one of `level`, `query`, or `parent_id` is required. example: 10 - in: query name: parent_level required: false schema: type: string enum: - region - subregion - country - state - county - city description: > The level that `parent_id` belongs to. Required whenever `parent_id` is provided, and ignored otherwise. example: country - in: query name: limit required: false schema: type: integer minimum: 1 maximum: 500 default: 100 description: > How many results to return, from 1 to 500. A value outside that range is rejected rather than clamped, so the page size you asked for is always the page size you got. example: 100 - in: query name: offset required: false schema: type: integer minimum: 0 default: 0 description: > How many results to skip. Combined with `limit` and the `total` reported in `pagination`, this walks the whole result set. example: 200 responses: '200': description: A JSON object containing the matching locations. content: application/json: schema: type: object properties: name: type: string description: The name of this result set. example: Locations pagination: type: object description: > Where this page sits in the full result set. `total` counts every match for the query, not just this page, so you can page through deterministically rather than requesting until a short page comes back. properties: limit: type: integer description: The page size that was applied. example: 100 offset: type: integer description: How many results were skipped. example: 0 total: type: integer description: Total matches for this query across every page. example: 3143 hasMore: type: boolean description: | Whether another page follows. Equivalent to `offset + results.length < total`. example: true results: type: array description: > The matching locations, capped at 500 entries and ordered coarsest level first, then cities by population descending. items: type: object properties: id: type: integer description: > The location identifier. Pass it to the `locations.` parameter named by `key`. Ids are unique only within a level. example: 6 name: type: string description: The location's display name. example: California level: type: string enum: - region - subregion - country - state - county - city description: The level of the taxonomy this location belongs to. example: state parent_id: type: - integer - 'null' description: > The id of this location's parent, or `null` for regions, which sit at the top of the taxonomy. A city's parent is its county when it has one, otherwise its state, otherwise its country — read `parent_level` to see which. example: 10 parent_level: type: - string - 'null' description: > The level that `parent_id` belongs to — one of `region`, `subregion`, `country`, `state`, or `county` — or `null` for regions. Pass this pair back as `parent_id` and `parent_level` to list the parent's other children. example: country key: type: string description: > The exact query-string parameter used to filter by this location elsewhere in the API, for example `locations.state[]=6`. example: locations.state standard: type: array description: > Every public-standard identifier this location carries. Most levels have one; `country` and `state` have two, because different mapping libraries key their shapes off different codes. - `region`, `subregion` — `un_m49` - `country` — `iso_3166_1_alpha2` and `iso_3166_1_alpha3` - `state` — `iso_3166_2_us` and `fips` - `county` — `fips` - `city` — `geonames_id` Note that a city's `geonames_id` is **not** its `id`. The `id` is this API's own identifier, and the one the `locations.city` filter takes. items: type: object properties: type: type: string enum: - un_m49 - iso_3166_1_alpha2 - iso_3166_1_alpha3 - iso_3166_2_us - fips - geonames_id description: The standard that `code` comes from. example: iso_3166_2_us code: type: string description: > The code itself. Always a string, so FIPS codes keep their leading zeros — `06` for California, `06001` for Alameda County. example: US-CA examples: by_level: summary: A state looked up by name value: name: Locations pagination: limit: 100 offset: 0 total: 1 hasMore: false results: - id: 6 name: California level: state parent_id: 10 parent_level: country key: locations.state standard: - type: iso_3166_2_us code: US-CA - type: fips code: '06' children: summary: The direct children of a state value: name: Locations pagination: limit: 100 offset: 0 total: 58 hasMore: false results: - id: 413 name: Alameda County level: county parent_id: 6 parent_level: state key: locations.county standard: - type: fips code: '06001' paged: summary: A page part-way through a large result set description: > Note that `id` and `standard.code` are different identifiers. `id` is the taxonomy's own id — the value the `locations.city` filter takes — while `standard.code` is the external GeoNames id for the same place. value: name: Locations pagination: limit: 100 offset: 200 total: 4213 hasMore: true results: - id: 512 name: San Francisco level: city parent_id: 6 parent_level: state key: locations.city standard: - type: geonames_id code: '5391959' '400': description: > The request is invalid. Causes include sending none of `level`, `query`, or `parent_id`; combining `level` with `parent_id`; a `level` or `parent_level` that is not one of the six taxonomy levels; sending `parent_id` without `parent_level`; a `query` shorter than 2 characters; and a `limit` or `offset` that is not an integer in range. '401': description: Missing or invalid access token. security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````