curl --request POST \
--url https://app.govly.com/api/tools/v1/places/list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"categories": [],
"isoCodes": [
"<string>"
],
"perPage": 25,
"cursor": "<string>",
"sort": "population",
"sortDirection": "desc"
}
'import requests
url = "https://app.govly.com/api/tools/v1/places/list"
payload = {
"categories": [],
"isoCodes": ["<string>"],
"perPage": 25,
"cursor": "<string>",
"sort": "population",
"sortDirection": "desc"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
categories: [],
isoCodes: ['<string>'],
perPage: 25,
cursor: '<string>',
sort: 'population',
sortDirection: 'desc'
})
};
fetch('https://app.govly.com/api/tools/v1/places/list', 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://app.govly.com/api/tools/v1/places/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'categories' => [
],
'isoCodes' => [
'<string>'
],
'perPage' => 25,
'cursor' => '<string>',
'sort' => 'population',
'sortDirection' => 'desc'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.govly.com/api/tools/v1/places/list"
payload := strings.NewReader("{\n \"categories\": [],\n \"isoCodes\": [\n \"<string>\"\n ],\n \"perPage\": 25,\n \"cursor\": \"<string>\",\n \"sort\": \"population\",\n \"sortDirection\": \"desc\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.govly.com/api/tools/v1/places/list")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"categories\": [],\n \"isoCodes\": [\n \"<string>\"\n ],\n \"perPage\": 25,\n \"cursor\": \"<string>\",\n \"sort\": \"population\",\n \"sortDirection\": \"desc\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.govly.com/api/tools/v1/places/list")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"categories\": [],\n \"isoCodes\": [\n \"<string>\"\n ],\n \"perPage\": 25,\n \"cursor\": \"<string>\",\n \"sort\": \"population\",\n \"sortDirection\": \"desc\"\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "<string>",
"name": "<string>",
"category": "postal_code",
"jurisdictionIsoCode": "<string>",
"hasRecords": true,
"nameMatch": "exact",
"population": 123,
"populationYear": 123,
"populationHistory": [
{
"year": 123,
"population": 123
}
]
}
],
"meta": {
"perPage": 123,
"returned": 123,
"total": 123,
"nextCursor": "<string>"
}
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}Enumerate every Place of a category within a jurisdiction
Enumerate every canonical Govly Place of a category within a jurisdiction — every county in California, every school district in Texas. At least one of categories or isoCodes is required. Without sort, ordering is stable but arbitrary, not alphabetical — page until meta.nextCursor is null for the whole set, and sort client-side when presenting a list. With sort population and sortDirection desc (largest first, default) or asc (smallest first), the N most or least populous places are the first N: request perPage N (following nextCursor only if meta.perPage is smaller than N). Places without a population sort last either way; population exists only for states, counties, and municipalities, and a population sort on any other category returns 400. Use /api/tools/v1/places/search instead to look up a place by name.
curl --request POST \
--url https://app.govly.com/api/tools/v1/places/list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"categories": [],
"isoCodes": [
"<string>"
],
"perPage": 25,
"cursor": "<string>",
"sort": "population",
"sortDirection": "desc"
}
'import requests
url = "https://app.govly.com/api/tools/v1/places/list"
payload = {
"categories": [],
"isoCodes": ["<string>"],
"perPage": 25,
"cursor": "<string>",
"sort": "population",
"sortDirection": "desc"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
categories: [],
isoCodes: ['<string>'],
perPage: 25,
cursor: '<string>',
sort: 'population',
sortDirection: 'desc'
})
};
fetch('https://app.govly.com/api/tools/v1/places/list', 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://app.govly.com/api/tools/v1/places/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'categories' => [
],
'isoCodes' => [
'<string>'
],
'perPage' => 25,
'cursor' => '<string>',
'sort' => 'population',
'sortDirection' => 'desc'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.govly.com/api/tools/v1/places/list"
payload := strings.NewReader("{\n \"categories\": [],\n \"isoCodes\": [\n \"<string>\"\n ],\n \"perPage\": 25,\n \"cursor\": \"<string>\",\n \"sort\": \"population\",\n \"sortDirection\": \"desc\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.govly.com/api/tools/v1/places/list")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"categories\": [],\n \"isoCodes\": [\n \"<string>\"\n ],\n \"perPage\": 25,\n \"cursor\": \"<string>\",\n \"sort\": \"population\",\n \"sortDirection\": \"desc\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.govly.com/api/tools/v1/places/list")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"categories\": [],\n \"isoCodes\": [\n \"<string>\"\n ],\n \"perPage\": 25,\n \"cursor\": \"<string>\",\n \"sort\": \"population\",\n \"sortDirection\": \"desc\"\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "<string>",
"name": "<string>",
"category": "postal_code",
"jurisdictionIsoCode": "<string>",
"hasRecords": true,
"nameMatch": "exact",
"population": 123,
"populationYear": 123,
"populationHistory": [
{
"year": 123,
"population": 123
}
]
}
],
"meta": {
"perPage": 123,
"returned": 123,
"total": 123,
"nextCursor": "<string>"
}
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Place categories to enumerate, such as county or school_district.
postal_code, county, municipality, region, country, military_installation, school_district Jurisdiction codes to enumerate within, matched exactly (e.g. US-CA). Not hierarchical — "US" matches only the country record. A bare foreign code such as "JP" scopes overseas military installations. At most 60 codes per call, which is above the 53 needed to cover every US state and territory at once.
60Results per page. Default 25, maximum 100.
x <= 100Opaque cursor from meta.nextCursor of the previous page. A cursor is bound to the filters and sort that produced it and is rejected if you change them.
population ranks by the latest census population; places without a population sort last. Omit for the default stable-but-arbitrary order.
population desc for most populous first, asc for least populous first. Requires sort.
asc, desc Was this page helpful?