Tutorial: US County Data

Geography

Data source: Curated dataset (US Census Bureau)

Overview

US County Data wraps Curated dataset (US Census Bureau), handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-us-county": {
      "url": "https://context.gnist.ai/mcp/us-county/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_county`

Get detailed information about a US county by its 5-digit FIPS code. Args: fips: 5-digit FIPS code (e.g. "06037" for Los Angeles County, CA). Returns: Dictionary with county details including population, area, and county seat.

Parameter	Type	Required	Description
`fips`	string	required

curl -X POST "https://context.gnist.ai/mcp/us-county/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_county", "arguments": {"fips": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-county/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'fips': 'example'}, 'name': 'get_county'}},
)
print(resp.json())

`search_counties`

Search US counties by name (case-insensitive partial match). Args: query: Search string to match against county names. limit: Maximum number of results to return (default 20). Returns: Dictionary with count and list of matching counties.

Parameter	Type	Required	Description
`query`	string	required
`limit`	integer	optional	(default: `20`)

curl -X POST "https://context.gnist.ai/mcp/us-county/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_counties", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-county/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_counties'}},
)
print(resp.json())

`list_counties_by_state`

List US counties in a given state, sorted by population descending. Args: state_code: Two-letter US state code (e.g. "CA", "TX", "NY"). limit: Maximum number of results to return (default 50). Returns: Dictionary with state, count, and list of counties.

Parameter	Type	Required	Description
`state_code`	string	required
`limit`	integer	optional	(default: `50`)

curl -X POST "https://context.gnist.ai/mcp/us-county/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_counties_by_state", "arguments": {"state_code": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-county/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'state_code': 'example'},
            'name': 'list_counties_by_state'}},
)
print(resp.json())

`get_states`

List all US states in the dataset with their county counts. Returns: Dictionary with total state count and list of states with county counts.

curl -X POST "https://context.gnist.ai/mcp/us-county/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_states", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-county/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'get_states'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/us-county/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-county/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_counties to find items, then get_county to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does US County Data provide?

US county-level data — population, area, FIPS codes, and county seats for ~200 US counties. It exposes 5 tools: get_county, search_counties, list_counties_by_state, get_states, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the US County Data API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.