Look up locations

curl --request GET \
  --url https://api.peakmetrics.com/locations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.peakmetrics.com/locations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.peakmetrics.com/locations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.peakmetrics.com/locations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.peakmetrics.com/locations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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"
        }
      ]
    }
  ]
}

Locations

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.<level> 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.

GET

locations

Look up locations

curl --request GET \
  --url https://api.peakmetrics.com/locations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.peakmetrics.com/locations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.peakmetrics.com/locations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.peakmetrics.com/locations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.peakmetrics.com/locations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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"
        }
      ]
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

level

enum<string>

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.

Available options:

region,

subregion,

country,

state,

county,

city

query

string

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.

Minimum string length: 2

parent_id

integer

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.

parent_level

enum<string>

The level that parent_id belongs to. Required whenever parent_id is provided, and ignored otherwise.

Available options:

region,

subregion,

country,

state,

county,

city

limit

integer

default:100

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.

Required range: 1 <= x <= 500

offset

integer

default:0

How many results to skip. Combined with limit and the total reported in pagination, this walks the whole result set.

Required range: x >= 0

Response

A JSON object containing the matching locations.

name

string

The name of this result set.

Example:

"Locations"

pagination

object

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.

Show child attributes

results

object[]

The matching locations, capped at 500 entries and ordered coarsest level first, then cities by population descending.

Show child attributes

⌘I