Docs
Quickstart
Palavue sells derived county measures for every US county. You can look around for free, then pay, get an API key, and pull data by REST, by the MCP connector, or as files. Everything below uses real examples from five sample counties: 06037 Los Angeles County, CA; 08093 Park County, CO; 25019 Nantucket County, MA; 36047 Kings County, NY; 48033 Borden County, TX.
- Look around with no key:
GET /v1/catalog,GET /v1/measures,GET /v1/counties?q=Nantucket. - Buy a plan on the product page. Your API key is shown once on the confirmation screen, which also has a button to download the edition ZIP.
- Store the key in an environment variable named
PALAVUE_KEY. Every authenticated call sendsAuthorization: Bearer <key>.
Search for a county (free, no key) GET /v1/counties?q=Nantucket&state=MA
curl
curl \
"https://api.palavue.com/v1/counties?q=Nantucket&state=MA"Python
import os, requests
r = requests.get("https://api.palavue.com/v1/counties?q=Nantucket&state=MA", headers={})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/counties?q=Nantucket&state=MA", {});
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/counties?q=Nantucket&state=MA") |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/counties?q=Nantucket&state=MA"))
.GET()
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
var json = await http.GetStringAsync("https://api.palavue.com/v1/counties?q=Nantucket&state=MA");
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.palavue.com/v1/counties?q=Nantucket&state=MA", nil)
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/counties?q=Nantucket&state=MA");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/counties?q=Nantucket&state=MA")
req = Net::HTTP::Get.new(uri, { })
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataGet one county, only two measures GET /v1/counties/25019?metrics=NC05,NC14
curl
curl \
-H "Authorization: Bearer $PALAVUE_KEY" \
"https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14"Python
import os, requests
r = requests.get("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14", headers={"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14", { headers: { Authorization: `Bearer ${process.env.PALAVUE_KEY}` } });
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14") |>
req_auth_bearer_token(Sys.getenv("PALAVUE_KEY")) |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14"))
.header("Authorization", "Bearer " + System.getenv("PALAVUE_KEY"))
.GET()
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("PALAVUE_KEY"));
var json = await http.GetStringAsync("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14");
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("PALAVUE_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PALAVUE_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/counties/25019?metrics=NC05,NC14")
req = Net::HTTP::Get.new(uri, { "Authorization" => "Bearer #{ENV['PALAVUE_KEY']}" })
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataAuthentication, limits and errors
- Send
Authorization: Bearer <key>. A key only works for the plan its owner bought. Keys are not shown again; if you lose one, sign in with your purchase email on the product page to create a new key and revoke the old one. - Free calls (catalog, measures, county search, quote, OpenAPI) need no key.
- Pay once and Subscribe: 60 requests a minute and 10,000 county records a day per key.
- On demand: 600 requests a minute and no daily cap. Billed monthly for the records you use.
- A request returns at most 100 counties. Use
afterto page. - A record is one county document returned. A 304 (not modified) response returns no record.
Errors are JSON with an HTTP status: {"error": "unknown_metric", "message": "...", ...extra fields}. Match on error, not on the message text.
| Status | error | Meaning and what to do |
|---|---|---|
| 400 | invalid_request, invalid_selection, invalid_metrics, no_counties, too_many_counties, invalid_fips | The request is malformed. The message says what to change. |
| 401 | unauthorized | Missing or wrong key. |
| 402 | payment_required, payment_failed, spend_cap_reached, card_required | No plan on the key, a declined On demand payment (requests pause until the card is replaced, see Spend controls), or your own spend cap. |
| 403 | not_entitled, not_available | The key's plan does not include this. |
| 404 | unknown_county | That FIPS code is not in this edition. The response lists the codes. |
| 422 | unknown_metric | A measure id is not in this edition. The response lists the valid ids. |
| 429 | rate_limited, daily_cap | Slow down, or (for the daily cap) move to On demand, which has none. |
| 5xx | stripe_error, send_failed | Try again later. |
Data structure
Every county is one JSON document, or the rows of county_measures.csv for that county. One row is one county, one measure.
{
"product": "county-economy-bundle",
"edition": "county-economy-2026-11-04",
"county": {"fips": "25019", "name": "Nantucket County", "state": "MA"},
"measures": [
{"metric_id": "NC14", "period": "2024-2025", "reported_value": 0.7557, "estimate_value": null,
"unit": "percent job growth", "status": "reported", "label": "Pay-led change",
"national_rank": 1109, "cohort_n": 2872, "estimate_method": null, "as_of": "2026-11-04"}
],
"notices": [{"topic": "missing", "notice": "A blank is missing. It is not zero."}],
"data_note": "...", "license": "..."
}
The county FIPS join key
Every county row carries county_fips, a five-character text code: two characters for the state and three for the county (Los Angeles County is 06037). Use it as the join key to any other county table, and keep it as text so leading zeros survive (in pandas dtype={"county_fips": str}; in Excel set the column to Text on import). Counties that have their own code are separate rows. It is not a ZIP code: ZIP in this product means the compressed download.
county_measures.csv (and each row of measures)
| Column | What it holds |
|---|---|
county_fips | Five-digit county code, as text. Keep leading zeros (01001, not 1001). |
state | Two-letter state code. |
county_name | County name. |
metric_id | Which measure: DC-01 or NC01 to NC15. Definitions in metric_library.csv. |
period | The timeframe the number covers (a year, a span like 2020-2025, or a quarter span). held for a measure not in this download. |
reported_value | The calculated number when the data exists. Empty if there is none. Never zero for missing. |
estimate_value | Only on estimated rows: the last reported value repeated onto a later finished timeframe. Not a forecast. |
unit | What the number is, for example dollars per job per year. |
status | reported, estimated, unavailable or held (see below). |
label | A short plain-words label on some measures, empty otherwise. |
national_rank | The county's position among the counties compared for that measure. 1 is the highest value. Empty when there is no reported value. |
cohort_n | How many counties were ranked for that measure. It differs between measures, so do not assume it is the number of counties. |
estimate_method | How an estimate was made (carry_forward_last_reported). Empty for reported rows. |
as_of | The edition date. |
| status | Meaning |
|---|---|
reported | A calculated number is in reported_value. |
estimated | reported_value is empty and estimate_value repeats the last reported value onto a later finished timeframe. No tested accuracy. When the real number is published it moves into reported_value. |
unavailable | The data needed for this county is missing, often because small counties suppress values. Both value columns are empty. |
held | The measure is not in this download (currently NC13). |
metric_library.csv
One row per measure. Columns: metric_id, name, question, number_means, unit, reported_period, estimate_periods, blank_means, cannot_say. Read number_means and cannot_say before you use a measure.
source_notices.csv
Columns topic and notice: what the number column is, how estimates work, the as-of date, what is held, and that a blank is missing. The same notices come back in every county document.
The measures
| Measure | Name | Unit | Period | Question it answers |
|---|---|---|---|---|
DC-01 | Workplaces relative to jobs | times the typical count | 2014-2023 | Does this county have more employer workplaces than counties with a similar number of jobs? |
NC01 | Workplaces after allowing for industry mix | times the expected count | 2023 | After allowing for the county's industries, is the workplace count still unusual? |
NC02 | Small workplaces beyond the industry mix | percentage points | 2023 | Are more of this county's workplaces small than its industries would suggest? |
NC03 | Workplace pattern over 2014–2023 | change in the log gap | 2014-2023 | Did the county's workplace pattern move up, down, or stay put? |
NC04 | Job growth versus peers | percentage points | 2020-2025 | Did private jobs grow more or less than counties with a similar industry mix and workplace pattern? |
NC05 | Pay versus peers | dollars per job per year | 2020-2025 | Is average private pay above or below counties with a similar industry mix, job count, and workplace pattern? |
NC06 | Replacement hiring versus peers | percentage points per quarter | 2024Q4-2025Q3 | Is the county replacing workers faster than similar counties? |
NC07 | Young-firm employment versus peers | percentage points | 2021-2023 | Do young firms account for more of the county's jobs than in similar counties? |
NC08 | Nonemployer businesses versus peers | times the expected density | 2023 | Are there more businesses with no employees than the county's size and income would suggest? |
NC09 | Seasonal job swing versus peers | percentage points | 2022-2025 | Does private employment rise and fall through the year more than in similar counties? |
NC10 | Jobs held by non-residents, versus peers | percentage points | 2022 | Do non-residents hold more of the county's jobs than in similar counties? |
NC11 | Household income versus the workplace profile | dollars | 2020-2024 | Is median household income above or below the level suggested by the county's jobs and workplace pattern? |
NC12 | Rent versus the workplace profile | times the expected rent | 2020-2024 | Is median rent high or low for the county's population, income, job growth, and workplace pattern? |
NC13 | Employment after a disaster declaration | percentage points | held | After a federal disaster declaration, how did private jobs compare with similar counties that were not designated? |
NC14 | Recent job, workplace, and pay profile | percent job growth | 2024-2025 | What happened to private jobs, workplaces, and pay from 2024 to 2025? |
NC15 | Older workforce and young firms | percentage points | 2024 / 2021-2023 | Does an older workforce sit alongside weaker young-firm activity than in peer counties? |
Fetch this table live from GET /v1/measures or the MCP tool get_measure_definitions. It is free and needs no key.
Choosing counties and measures
Counties are identified by five-digit FIPS codes. Find a code with the free search, then pull.
One county by FIPS code GET /v1/counties/06037
curl
curl \
-H "Authorization: Bearer $PALAVUE_KEY" \
"https://api.palavue.com/v1/counties/06037"Python
import os, requests
r = requests.get("https://api.palavue.com/v1/counties/06037", headers={"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/counties/06037", { headers: { Authorization: `Bearer ${process.env.PALAVUE_KEY}` } });
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/counties/06037") |>
req_auth_bearer_token(Sys.getenv("PALAVUE_KEY")) |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/counties/06037"))
.header("Authorization", "Bearer " + System.getenv("PALAVUE_KEY"))
.GET()
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("PALAVUE_KEY"));
var json = await http.GetStringAsync("https://api.palavue.com/v1/counties/06037");
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.palavue.com/v1/counties/06037", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("PALAVUE_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/counties/06037");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PALAVUE_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/counties/06037")
req = Net::HTTP::Get.new(uri, { "Authorization" => "Bearer #{ENV['PALAVUE_KEY']}" })
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataSeveral counties by list POST /v1/pull
curl
curl \
-X POST \
-H "Authorization: Bearer $PALAVUE_KEY" \
-H "Content-Type: application/json" \
-d '{"counties": ["06037", "08093", "25019"]}' \
"https://api.palavue.com/v1/pull"Python
import os, requests
r = requests.post("https://api.palavue.com/v1/pull", headers={"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]}, json={"counties": ["06037", "08093", "25019"]})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/pull", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PALAVUE_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({"counties": ["06037", "08093", "25019"]}),
});
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/pull") |>
req_auth_bearer_token(Sys.getenv("PALAVUE_KEY")) |>
req_body_json(list("counties" = c("06037", "08093", "25019"))) |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/pull"))
.header("Authorization", "Bearer " + System.getenv("PALAVUE_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{\"counties\": [\"06037\", \"08093\", \"25019\"]}"))
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("PALAVUE_KEY"));
var response = await http.PostAsync("https://api.palavue.com/v1/pull",
new StringContent("{\"counties\": [\"06037\", \"08093\", \"25019\"]}", System.Text.Encoding.UTF8, "application/json"));
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.palavue.com/v1/pull", strings.NewReader(`{"counties": ["06037", "08093", "25019"]}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("PALAVUE_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/pull");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"counties": ["06037", "08093", "25019"]}',
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PALAVUE_KEY"), "Content-Type: application/json"],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/pull")
req = Net::HTTP::Post.new(uri, { "Authorization" => "Bearer #{ENV['PALAVUE_KEY']}", "Content-Type" => "application/json" })
req.body = '{"counties": ["06037", "08093", "25019"]}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataEvery county in one or more states POST /v1/pull
curl
curl \
-X POST \
-H "Authorization: Bearer $PALAVUE_KEY" \
-H "Content-Type: application/json" \
-d '{"states": ["CO", "MA"]}' \
"https://api.palavue.com/v1/pull"Python
import os, requests
r = requests.post("https://api.palavue.com/v1/pull", headers={"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]}, json={"states": ["CO", "MA"]})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/pull", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PALAVUE_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({"states": ["CO", "MA"]}),
});
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/pull") |>
req_auth_bearer_token(Sys.getenv("PALAVUE_KEY")) |>
req_body_json(list("states" = c("CO", "MA"))) |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/pull"))
.header("Authorization", "Bearer " + System.getenv("PALAVUE_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{\"states\": [\"CO\", \"MA\"]}"))
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("PALAVUE_KEY"));
var response = await http.PostAsync("https://api.palavue.com/v1/pull",
new StringContent("{\"states\": [\"CO\", \"MA\"]}", System.Text.Encoding.UTF8, "application/json"));
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.palavue.com/v1/pull", strings.NewReader(`{"states": ["CO", "MA"]}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("PALAVUE_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/pull");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"states": ["CO", "MA"]}',
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PALAVUE_KEY"), "Content-Type: application/json"],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/pull")
req = Net::HTTP::Post.new(uri, { "Authorization" => "Bearer #{ENV['PALAVUE_KEY']}", "Content-Type" => "application/json" })
req.body = '{"states": ["CO", "MA"]}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataEvery county, only one measure POST /v1/pull
curl
curl \
-X POST \
-H "Authorization: Bearer $PALAVUE_KEY" \
-H "Content-Type: application/json" \
-d '{"all": true, "metrics": ["NC05"], "limit": 100}' \
"https://api.palavue.com/v1/pull"Python
import os, requests
r = requests.post("https://api.palavue.com/v1/pull", headers={"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]}, json={"all": true, "metrics": ["NC05"], "limit": 100})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/pull", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PALAVUE_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({"all": true, "metrics": ["NC05"], "limit": 100}),
});
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/pull") |>
req_auth_bearer_token(Sys.getenv("PALAVUE_KEY")) |>
req_body_json(list("all" = TRUE, "metrics" = c("NC05"), "limit" = 100)) |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/pull"))
.header("Authorization", "Bearer " + System.getenv("PALAVUE_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{\"all\": true, \"metrics\": [\"NC05\"], \"limit\": 100}"))
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("PALAVUE_KEY"));
var response = await http.PostAsync("https://api.palavue.com/v1/pull",
new StringContent("{\"all\": true, \"metrics\": [\"NC05\"], \"limit\": 100}", System.Text.Encoding.UTF8, "application/json"));
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.palavue.com/v1/pull", strings.NewReader(`{"all": true, "metrics": ["NC05"], "limit": 100}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("PALAVUE_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/pull");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"all": true, "metrics": ["NC05"], "limit": 100}',
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PALAVUE_KEY"), "Content-Type: application/json"],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/pull")
req = Net::HTTP::Post.new(uri, { "Authorization" => "Bearer #{ENV['PALAVUE_KEY']}", "Content-Type" => "application/json" })
req.body = '{"all": true, "metrics": ["NC05"], "limit": 100}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataChoosing measures with metrics
Add metrics to any pull to return only those measures. On GET /v1/counties/{fips} it is a comma list: ?metrics=NC05,NC14. In a POST /v1/pull body or an MCP call it is a list: ["NC05","DC-01"]. Ids are case-insensitive, up to 40. An unknown id returns 422 unknown_metric with the list of valid ids. The returned document gains metrics_filter showing what was applied. A record is still one county, however many measures you ask for.
Paging through many counties
A pull returns up to 100 counties and a next cursor (a FIPS code), or null on the last page. Send it back as after. total is how many counties your selection has.
import os, requests
headers = {"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]}
body = {"all": True, "metrics": ["NC05"], "limit": 100}
counties, after = [], None
while True:
if after:
body["after"] = after
r = requests.post("https://api.palavue.com/v1/pull", headers=headers, json=body)
r.raise_for_status()
page = r.json()
counties += page["counties"]
after = page["next"] # None on the last page
if not after:
break
print(len(counties), "counties")
const headers = { Authorization: `Bearer ${process.env.PALAVUE_KEY}`, "Content-Type": "application/json" };
const body = { all: true, metrics: ["NC05"], limit: 100 };
const counties = [];
let after = null;
do {
const r = await fetch("https://api.palavue.com/v1/pull", { method: "POST", headers, body: JSON.stringify({ ...body, ...(after ? { after } : {}) }) });
if (!r.ok) throw new Error(await r.text());
const page = await r.json();
counties.push(...page.counties);
after = page.next; // null on the last page
} while (after);
console.log(counties.length, "counties");
after=""
while :; do
body='{"all":true,"metrics":["NC05"],"limit":100'${after:+,\"after\":\"$after\"}'}'
page=$(curl -s -X POST -H "Authorization: Bearer $PALAVUE_KEY" -H "Content-Type: application/json" -d "$body" https://api.palavue.com/v1/pull)
echo "$page" | jq -c '.counties[]' >> counties.jsonl
after=$(echo "$page" | jq -r '.next // empty')
[ -z "$after" ] && break
done
wc -l counties.jsonl
Caching with ETag
GET /v1/counties/{fips} returns an ETag. Send it back in If-None-Match; if the county has not changed you get 304 and no record is counted. Response headers also carry X-Edition (which edition), X-Plan and X-Cache.
Files and downloads
Each edition is also a ZIP: county_measures.csv (all counties, all measures), metric_library.csv, source_notices.csv. The checkout confirmation has a download button. You can also request download links with your key or by email code (POST /v1/download, /v1/download/list, /v1/download/email, /v1/download/verify). Pay once: the edition you bought stays downloadable until a newer edition is published, plus 90 days. Subscribe: every edition while the subscription is active. Access is by your API key, the 24-hour link on the confirmation screen, or a 6-digit code emailed to your purchase address. Up to 20 downloads a day. Download and keep your copy.
A free sample (five counties, three measures) is at palavue-county-sample.csv.
import pandas as pd
df = pd.read_csv("county_measures.csv", dtype={"county_fips": str})
nc05 = df[(df.metric_id == "NC05") & (df.status == "reported")]
print(nc05.sort_values("national_rank").head(10)[["county_name", "state", "reported_value", "national_rank"]])
library(readr); library(dplyr)
df <- read_csv("county_measures.csv", col_types = cols(county_fips = col_character()))
df |> filter(metric_id == "NC05", status == "reported") |> arrange(national_rank) |> head(10)
In Excel: Data > From Text/CSV, then set county_fips to Text on import so leading zeros stay. In Google Sheets: File > Import, with "Convert text to numbers" off for that column, or use the Apps Script below.
// Google Sheets: Extensions > Apps Script. Store the key under Project Settings > Script properties as PALAVUE_KEY.
function palavueCounty(fips, metrics) {
var key = PropertiesService.getScriptProperties().getProperty("PALAVUE_KEY");
var url = "https://api.palavue.com/v1/counties/" + fips + (metrics ? "?metrics=" + metrics : "");
var res = UrlFetchApp.fetch(url, { headers: { Authorization: "Bearer " + key } });
var rows = JSON.parse(res.getContentText()).measures;
return [["metric_id", "period", "reported_value", "estimate_value", "status", "national_rank"]]
.concat(rows.map(function (m) { return [m.metric_id, m.period, m.reported_value, m.estimate_value, m.status, m.national_rank]; }));
}
// In a cell: =palavueCounty("25019", "NC05,NC14")
// Excel: Data > Get Data > From Other Sources > Blank Query > Advanced Editor. Put the key in a parameter named PalavueKey.
let
Source = Json.Document(Web.Contents("https://api.palavue.com/v1/counties/25019",
[Query = [metrics = "NC05,NC14"], Headers = [Authorization = "Bearer " & PalavueKey]])),
Measures = Table.FromRecords(Source[measures])
in
Measures
Which format to use
CSV and ZIP are the whole edition as a file: use them for a full pass in a spreadsheet or a data tool. The API returns the same edition one request at a time: use it from a program. MCP exposes the same edition as tools for an AI assistant. The three channels contain the same numbers; the edition date is on every row (as_of).
How to cite a county measure
Name Palavue, the County Economy Bundle, the edition date, the measure name and its period, for example: Palavue, County Economy Bundle, edition 2026-11-04, Pay versus peers (NC05), 2020 to 2025. The figure is a derived comparison, not a reprint of an agency table, so describe it that way and do not suggest that any agency endorses it. How you may publish charts and short excerpts is in the Legal page.
Connect with MCP
The MCP connector is a remote server at https://api.palavue.com/mcp (Streamable HTTP). Free tools need no key. Tools that read county values need your key as Authorization: Bearer <key>.
Setup in a client that supports remote MCP servers: add a custom or remote connector, set the URL to the address above, and, where the client has a header or token field, add Authorization with Bearer <your key>. Clients differ in where that field lives; check the client's own documentation for "remote MCP server".
{
"mcpServers": {
"palavue": {
"type": "http",
"url": "https://api.palavue.com/mcp",
"headers": {"Authorization": "Bearer YOUR_KEY"}
}
}
}
| Tool | What it does |
|---|---|
search_counties | Find counties by name or state. Free. Returns FIPS codes, no values. |
get_catalog | Edition, the three plans, prices and limits. Free. |
get_measure_definitions | What every measure means: question, unit, periods, what a blank means. Free. |
quote_order | Price a plan. Free, buys nothing. Returns a cart_url for a person to review and pay. |
get_county | One county's measures (optionally only some measures). Needs a key. |
get_counties | Counties by list, by state or all, a page at a time (up to 100). Needs a key. |
get_feed_updates | Whether a newer edition exists. Needs a key. |
get_account | Your plan, usage and amount not yet invoiced. Needs a key. |
get_spend_controls | Your On demand spend cap and alerts. Needs a key. |
set_spend_controls | Set or clear the cap, alert levels, alert email and webhook. Needs a key. |
get_notifications | Your spend notifications. Needs a key. |
get_county and get_counties take the same metrics list as REST. get_counties pages with after and returns next.
Using it from an AI assistant
An assistant calls these tools; it does not read the website. Ask for one county or a short list, and ask it to report the measure name, period, value, unit and rank together with what the measure cannot say (get_measure_definitions returns the definitions). The free tools need no key; the tools that read county values need your key. Example request: "Using the Palavue tools, get Pay versus peers (NC05) for county 06037 and explain what the number means and what it does not."
Endpoint reference
Base URL https://api.palavue.com. Full machine-readable description: /v1/openapi.json.
| Method | Path | Key | What it does |
|---|---|---|---|
GET | /v1/catalog | No | Edition, plans, prices and limits. |
GET | /v1/measures | No | Definitions of every measure. |
GET | /v1/counties | No | Search counties by name or state (?q=, ?state=, ?limit= up to 200). Returns FIPS codes only. |
POST | /v1/quote | No | Price a plan. Body {"plan": "once" | "subscription" | "ondemand"}. Returns a cart_url. |
GET | /v1/openapi.json | No | Machine-readable API description. |
GET | /v1/counties/{fips} | Yes | One county. Optional ?metrics=NC05,NC14. Supports If-None-Match. |
POST | /v1/pull | Yes | Counties by list, by state or all, a page at a time. Optional metrics, limit, after. |
GET | /v1/feed | Yes | Latest edition and whether it is newer than ?since=<edition>. |
GET | /v1/me | Yes | Your plan, usage and limits. |
GET / POST | /v1/spend-controls | Yes | On demand only: read or set the spend cap, alerts, alert email and webhook. |
GET / POST | /v1/notifications | Yes | Spend notifications (?unread=1). POST returns the list and marks it read. |
POST | /v1/stripe/card | Yes | Returns a link to add or replace the card on file. |
POST | /v1/download | Yes | Edition ZIP downloads (see Files and downloads). |
POST | /v1/download/email | No | Email a 6-digit sign-in code to a purchase email (same answer whether or not the email has a purchase). |
POST | /v1/download/verify | No | Exchange the code for a 30-minute session token. |
GET | /v1/account | Session | Your plans, orders, keys (prefix, label, created, active) and requests in the last 30 days. Send the token in the X-Account-Session header. |
POST | /v1/account/keys | Session | Create a key (shown once; up to five active keys). Body: optional label, customer_id. |
POST | /v1/account/keys/revoke | Session | Revoke a key. Body: key_id. |
POST | /v1/contact | No | The contact form behind the Contact page. |
POST | /mcp | Mixed | The remote MCP endpoint (Streamable HTTP, JSON-RPC). |
On demand, spend controls and your card
On demand is an add-on to Pay once or Subscribe. It has no cap and no monthly fee: you pay $2 per 1,000 county records, billed monthly to the card you paid with, with a $5 minimum invoice (smaller amounts roll over). The card is saved at checkout. If a monthly payment is declined, requests pause until you replace the card and the amount owed is paid.
GET /v1/meshows records used and the amount not yet invoiced.POST /v1/spend-controlssetscap_usd(requests stop at the cap),alert_usd,alert_percents,emailandwebhook_url.GETreads them. On demand keys only.GET /v1/notificationslists alerts.POST /v1/stripe/cardreturns a link to add or replace the card.
Set a monthly spend cap POST /v1/spend-controls
curl
curl \
-X POST \
-H "Authorization: Bearer $PALAVUE_KEY" \
-H "Content-Type: application/json" \
-d '{"cap_usd": 50, "alert_percents": [50, 80]}' \
"https://api.palavue.com/v1/spend-controls"Python
import os, requests
r = requests.post("https://api.palavue.com/v1/spend-controls", headers={"Authorization": "Bearer " + os.environ["PALAVUE_KEY"]}, json={"cap_usd": 50, "alert_percents": [50, 80]})
r.raise_for_status()
data = r.json()
print(data)JavaScript
const r = await fetch("https://api.palavue.com/v1/spend-controls", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PALAVUE_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({"cap_usd": 50, "alert_percents": [50, 80]}),
});
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
console.log(data);R
library(httr2)
resp <- request("https://api.palavue.com/v1/spend-controls") |>
req_auth_bearer_token(Sys.getenv("PALAVUE_KEY")) |>
req_body_json(list("cap_usd" = 50, "alert_percents" = c(50, 80))) |>
req_perform()
data <- resp_body_json(resp)
str(data, max.level = 2)Java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.palavue.com/v1/spend-controls"))
.header("Authorization", "Bearer " + System.getenv("PALAVUE_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{\"cap_usd\": 50, \"alert_percents\": [50, 80]}"))
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());C#
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("PALAVUE_KEY"));
var response = await http.PostAsync("https://api.palavue.com/v1/spend-controls",
new StringContent("{\"cap_usd\": 50, \"alert_percents\": [50, 80]}", System.Text.Encoding.UTF8, "application/json"));
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);Go
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.palavue.com/v1/spend-controls", strings.NewReader(`{"cap_usd": 50, "alert_percents": [50, 80]}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("PALAVUE_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}
PHP
$ch = curl_init("https://api.palavue.com/v1/spend-controls");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"cap_usd": 50, "alert_percents": [50, 80]}',
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PALAVUE_KEY"), "Content-Type: application/json"],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);Ruby
require "net/http"
require "json"
uri = URI("https://api.palavue.com/v1/spend-controls")
req = Net::HTTP::Post.new(uri, { "Authorization" => "Bearer #{ENV['PALAVUE_KEY']}", "Content-Type" => "application/json" })
req.body = '{"cap_usd": 50, "alert_percents": [50, 80]}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts dataCode in nine languages
Every example above is shown in curl, Python, JavaScript, R, Java, C#, Go, PHP and Ruby; open the language you need. They all read the key from PALAVUE_KEY.
Versions and changes
The API is versioned in the path (/v1). We say what exists today and promise no schedule for changes. Fields may be added without a version change, so ignore fields you do not recognize.