Menu

API Documentation

Programmatic access to K-12 school district data

API Access

Full access to REST API and MCP server

  • 10,000 API requests/day
  • All REST endpoints + MCP server
  • Cancel anytime
$49/month
Subscribe

This data is aggregated from state and federal public datasets. While we believe it is accurate, we always recommend confirming it on the corresponding state or federal site. See Data Notes for more.

Overview

The EduSignal API provides RESTful access to normalized K-12 school district data for all 50 states and Washington D.C. The API returns data only — no AI analysis or scoring is included. Consumers bring their own intelligence layer.

Base URL: https://edusignal.ai/api/v1
13,000+
Districts
50
States + DC
40+
Data Points

Authentication

Bearer Token

All API requests require an API key passed in the Authorization header.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://edusignal.ai/api/v1/districts/3704320

Getting an API Key

  1. Subscribe to API access ($49/month) via the Pricing section below.
  2. After payment, your API key will be displayed once. Copy and store it securely.
  3. The key prefix (e.g., edus_a1b2...) is visible in your account settings for reference.

Security Note:Your full API key is only shown once at creation. If you lose it, you'll need to regenerate a new key from your account settings.

Rate Limits

Daily and Burst Limits

Rate limits are applied per API key to ensure fair usage.

10,000
Requests per day
20
Requests per second (burst)

Rate Limit Headers

Every response includes rate limit information in the headers:

HeaderDescription
X-RateLimit-LimitMaximum requests per day (10000)
X-RateLimit-RemainingRequests remaining in current period
X-RateLimit-ResetUTC timestamp when limit resets (midnight UTC)

429 Response

When rate limits are exceeded, the API returns a 429 status with a Retry-After header:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Daily rate limit of 10,000 requests exceeded. Resets at midnight UTC.",
    "retry_after": 3600
  }
}

Endpoints

GET/api/v1/districts/{ncesId}

Returns a full district profile including enrollment, demographics, academics, finances, staffing, and AI-generated summary.

Path Parameters

NameTypeDescription
ncesIdstring7-digit NCES district ID (e.g., 3704320)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://edusignal.ai/api/v1/districts/3704320

Example Response

{
  "nces_id": "3704320",
  "name": "Wake County Public School System",
  "state_code": "NC",
  "state_name": "North Carolina",
  "county": "Wake",
  "locale_type": "Suburb",
  "region": "Southeast",
  "website_url": "https://www.wcpss.net",
  "enrollment": {
    "total": 160000,
    "prior_year": 158000,
    "trend_pct": 1.27,
    "data_year": "2022-23"
  },
  "schools": {
    "total": 196,
    "elementary": 118,
    "middle": 37,
    "high": 31,
    "other": 10
  },
  "staffing": {
    "teacher_count": 10500,
    "student_teacher_ratio": 15.2,
    "total_staff": 19500,
    "counselor_count": 350,
    "student_counselor_ratio": 457.1,
    "psychologist_count": 45,
    "student_psychologist_ratio": 3555.6,
    "paraprofessional_count": 2800,
    "librarian_count": 196
  },
  "finance": {
    "per_pupil_spending": 10250,
    "total_budget": 1640000000,
    "pct_federal_revenue": 8.5,
    "pct_state_revenue": 52.3,
    "pct_local_revenue": 39.2,
    "data_year": "2021-22"
  },
  "demographics": {
    "pct_frpl": 32.5,
    "pct_ell": 12.3,
    "pct_swd": 13.1,
    "pct_white": 42.1,
    "pct_black": 22.3,
    "pct_hispanic": 20.5,
    "pct_asian": 10.2,
    "pct_two_or_more": 4.9,
    "pct_other": 0,
    "data_year": "2022-23"
  },
  "academics": {
    "math_proficiency": 48.2,
    "reading_proficiency": 52.1,
    "graduation_rate": 91.2,
    "dropout_rate": 2.1,
    "chronic_absenteeism": 14.3,
    "data_year": "2022-23"
  },
  "ai_summary": "Wake County Public School System is the largest district in North Carolina and one of the 15 largest in the United States, serving approximately 160,000 students across 196 schools...",
  "summary_generated_at": "2026-05-01T12:00:00.000Z",
  "federal_data_year": "2022-23",
  "state_data_year": "2022-23"
}
GET/api/v1/districts/search

Search and filter districts with cursor-based pagination.

Query Parameters

NameTypeDescription
statestring2-letter state code (e.g., NC, CA)
enrollment_minintegerMinimum enrollment
enrollment_maxintegerMaximum enrollment
localestringComma-separated locale types (City, Suburb, Town, Rural)
frpl_minnumberMinimum FRPL percentage (0-100)
frpl_maxnumberMaximum FRPL percentage (0-100)
math_proficiency_minnumberMinimum math proficiency (0-100)
math_proficiency_maxnumberMaximum math proficiency (0-100)
reading_proficiency_minnumberMinimum reading proficiency (0-100)
reading_proficiency_maxnumberMaximum reading proficiency (0-100)
pps_minnumberMinimum per-pupil spending
pps_maxnumberMaximum per-pupil spending
cursorstringPagination cursor from previous response
limitintegerResults per page (default 50, max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://edusignal.ai/api/v1/districts/search?state=NC&enrollment_min=10000&limit=10"

Example Response

{
  "data": [
    {
      "nces_id": "3704320",
      "name": "Wake County Public School System",
      "state_code": "NC",
      "state_name": "North Carolina",
      "county": "Wake",
      "locale_type": "Suburb",
      "region": "Southeast",
      "website_url": "https://www.wcpss.net",
      "enrollment": {
        "total": 160000,
        "prior_year": 158000,
        "trend_pct": 1.27,
        "data_year": "2022-23"
      },
      "schools": {
        "total": 196,
        "elementary": 118,
        "middle": 37,
        "high": 31,
        "other": 10
      },
      "staffing": {
        "teacher_count": 10500,
        "student_teacher_ratio": 15.2,
        "total_staff": 19500,
        "counselor_count": 350,
        "student_counselor_ratio": 457.1,
        "psychologist_count": 45,
        "student_psychologist_ratio": 3555.6,
        "paraprofessional_count": 2800,
        "librarian_count": 196
      },
      "finance": {
        "per_pupil_spending": 10250,
        "total_budget": 1640000000,
        "pct_federal_revenue": 8.5,
        "pct_state_revenue": 52.3,
        "pct_local_revenue": 39.2,
        "data_year": "2021-22"
      },
      "demographics": {
        "pct_frpl": 32.5,
        "pct_ell": 12.3,
        "pct_swd": 13.1,
        "pct_white": 42.1,
        "pct_black": 22.3,
        "pct_hispanic": 20.5,
        "pct_asian": 10.2,
        "pct_two_or_more": 4.9,
        "pct_other": 0,
        "data_year": "2022-23"
      },
      "academics": {
        "math_proficiency": 48.2,
        "reading_proficiency": 52.1,
        "graduation_rate": 91.2,
        "dropout_rate": 2.1,
        "chronic_absenteeism": 14.3,
        "data_year": "2022-23"
      },
      "ai_summary": "Wake County Public School System is the largest district in North Carolina and one of the 15 largest in the United States, serving approximately 160,000 students across 196 schools...",
      "summary_generated_at": "2026-05-01T12:00:00.000Z",
      "federal_data_year": "2022-23",
      "state_data_year": "2022-23"
    }
  ],
  "next_cursor": "MTA=",
  "total_count": 25
}
GET/api/v1/districts/{ncesId}/schools

Returns aggregate school counts for a district by level. Individual school records are not currently available.

Path Parameters

NameTypeDescription
ncesIdstring7-digit NCES district ID

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://edusignal.ai/api/v1/districts/3704320/schools

Example Response

{
  "district_nces_id": "3704320",
  "district_name": "Wake County Public School System",
  "schools": {
    "total": 196,
    "elementary": 118,
    "middle": 37,
    "high": 31,
    "other": 10
  },
  "note": "Individual school records are not available. This endpoint returns aggregate school counts by level."
}
GET/api/v1/states

Returns a list of all states with aggregate education statistics.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://edusignal.ai/api/v1/states

Example Response

{
  "data": [
    {
      "code": "NC",
      "name": "North Carolina",
      "is_active": true,
      "total_enrollment": 1550000,
      "total_districts": 115,
      "total_schools": 2650,
      "total_teachers": 98500,
      "total_budget": 15500000000,
      "avg_per_pupil_spending": 10000,
      "avg_math_proficiency": 45.2,
      "avg_reading_proficiency": 48.5,
      "avg_graduation_rate": 88.5,
      "pct_frpl": 45.2,
      "pct_ell": 10.5,
      "pct_swd": 14.2,
      "federal_data_year": "2022-23",
      "state_data_year": "2022-23"
    }
  ]
}
GET/api/v1/states/{stateCode}

Returns state-level aggregate data including enrollment, spending averages, and proficiency rates.

Path Parameters

NameTypeDescription
stateCodestring2-letter state abbreviation (e.g., NC, TX)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://edusignal.ai/api/v1/states/NC

Example Response

{
  "code": "NC",
  "name": "North Carolina",
  "is_active": true,
  "total_enrollment": 1550000,
  "total_districts": 115,
  "total_schools": 2650,
  "total_teachers": 98500,
  "total_budget": 15500000000,
  "avg_per_pupil_spending": 10000,
  "avg_math_proficiency": 45.2,
  "avg_reading_proficiency": 48.5,
  "avg_graduation_rate": 88.5,
  "pct_frpl": 45.2,
  "pct_ell": 10.5,
  "pct_swd": 14.2,
  "federal_data_year": "2022-23",
  "state_data_year": "2022-23"
}
GET/api/v1/states/{stateCode}/districts

Returns all districts in a state with cursor-based pagination, ordered by enrollment (largest first).

Path Parameters

NameTypeDescription
stateCodestring2-letter state abbreviation

Query Parameters

NameTypeDescription
cursorstringPagination cursor from previous response
limitintegerResults per page (default 50, max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://edusignal.ai/api/v1/states/NC/districts?limit=10"

Example Response

{
  "data": [
    {
      "nces_id": "3704320",
      "name": "Wake County Public School System",
      "state_code": "NC",
      "state_name": "North Carolina",
      "county": "Wake",
      "locale_type": "Suburb",
      "region": "Southeast",
      "website_url": "https://www.wcpss.net",
      "enrollment": {
        "total": 160000,
        "prior_year": 158000,
        "trend_pct": 1.27,
        "data_year": "2022-23"
      },
      "schools": {
        "total": 196,
        "elementary": 118,
        "middle": 37,
        "high": 31,
        "other": 10
      },
      "staffing": {
        "teacher_count": 10500,
        "student_teacher_ratio": 15.2,
        "total_staff": 19500,
        "counselor_count": 350,
        "student_counselor_ratio": 457.1,
        "psychologist_count": 45,
        "student_psychologist_ratio": 3555.6,
        "paraprofessional_count": 2800,
        "librarian_count": 196
      },
      "finance": {
        "per_pupil_spending": 10250,
        "total_budget": 1640000000,
        "pct_federal_revenue": 8.5,
        "pct_state_revenue": 52.3,
        "pct_local_revenue": 39.2,
        "data_year": "2021-22"
      },
      "demographics": {
        "pct_frpl": 32.5,
        "pct_ell": 12.3,
        "pct_swd": 13.1,
        "pct_white": 42.1,
        "pct_black": 22.3,
        "pct_hispanic": 20.5,
        "pct_asian": 10.2,
        "pct_two_or_more": 4.9,
        "pct_other": 0,
        "data_year": "2022-23"
      },
      "academics": {
        "math_proficiency": 48.2,
        "reading_proficiency": 52.1,
        "graduation_rate": 91.2,
        "dropout_rate": 2.1,
        "chronic_absenteeism": 14.3,
        "data_year": "2022-23"
      },
      "ai_summary": "Wake County Public School System is the largest district in North Carolina and one of the 15 largest in the United States, serving approximately 160,000 students across 196 schools...",
      "summary_generated_at": "2026-05-01T12:00:00.000Z",
      "federal_data_year": "2022-23",
      "state_data_year": "2022-23"
    }
  ],
  "next_cursor": "MTA=",
  "total_count": 115
}
POST/api/v1/compare

Returns side-by-side data for 2-10 districts. Districts are returned in the same order as the request.

Request Body

NameTypeDescription
nces_idsstring[]Array of 2-10 NCES district IDs to compare

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nces_ids": ["3704320", "3704380", "3704410"]}' \
  https://edusignal.ai/api/v1/compare

Example Response

{
  "data": [
    {
      "nces_id": "3704320",
      "name": "Wake County Public School System",
      "state_code": "NC",
      "state_name": "North Carolina",
      "county": "Wake",
      "locale_type": "Suburb",
      "region": "Southeast",
      "website_url": "https://www.wcpss.net",
      "enrollment": {
        "total": 160000,
        "prior_year": 158000,
        "trend_pct": 1.27,
        "data_year": "2022-23"
      },
      "schools": {
        "total": 196,
        "elementary": 118,
        "middle": 37,
        "high": 31,
        "other": 10
      },
      "staffing": {
        "teacher_count": 10500,
        "student_teacher_ratio": 15.2,
        "total_staff": 19500,
        "counselor_count": 350,
        "student_counselor_ratio": 457.1,
        "psychologist_count": 45,
        "student_psychologist_ratio": 3555.6,
        "paraprofessional_count": 2800,
        "librarian_count": 196
      },
      "finance": {
        "per_pupil_spending": 10250,
        "total_budget": 1640000000,
        "pct_federal_revenue": 8.5,
        "pct_state_revenue": 52.3,
        "pct_local_revenue": 39.2,
        "data_year": "2021-22"
      },
      "demographics": {
        "pct_frpl": 32.5,
        "pct_ell": 12.3,
        "pct_swd": 13.1,
        "pct_white": 42.1,
        "pct_black": 22.3,
        "pct_hispanic": 20.5,
        "pct_asian": 10.2,
        "pct_two_or_more": 4.9,
        "pct_other": 0,
        "data_year": "2022-23"
      },
      "academics": {
        "math_proficiency": 48.2,
        "reading_proficiency": 52.1,
        "graduation_rate": 91.2,
        "dropout_rate": 2.1,
        "chronic_absenteeism": 14.3,
        "data_year": "2022-23"
      },
      "ai_summary": "Wake County Public School System is the largest district in North Carolina and one of the 15 largest in the United States, serving approximately 160,000 students across 196 schools...",
      "summary_generated_at": "2026-05-01T12:00:00.000Z",
      "federal_data_year": "2022-23",
      "state_data_year": "2022-23"
    }
  ]
}

Error Codes

All errors follow a consistent JSON format with an error object containing code, message, and optional retry_after.

CodeHTTP StatusDescription
unauthorized401Missing or invalid API key
not_found404Resource (district, state) not found
rate_limit_exceeded429Daily or burst rate limit exceeded
invalid_request400Invalid parameters or request body
server_error500Internal server error

MCP Server

Model Context Protocol

Connect AI assistants like Claude directly to EduSignal data using the MCP protocol.

Endpoint: https://edusignal.ai/mcp
Protocol: JSON-RPC 2.0 over HTTP

Connection

The MCP server uses the same API key as the REST API. Include your key in the Authorization header:

curl -X POST https://edusignal.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1}'

Available Tools

lookup_district

Look up a K-12 school district profile by NCES ID or by name and state. Returns enrollment, demographics, academic performance, finances, and an AI-generated summary.

Parameters:
  • nces_id — 7-digit NCES district ID
  • name — District name (partial match)
  • state — State code or name

Either nces_id or both name + state required

search_districts

Search for K-12 school districts matching specific criteria. Returns up to 20 results per call. Use filters to narrow results.

Parameters:
  • state — 2-letter state code
  • enrollment_min / enrollment_max
  • locale — Array: City, Suburb, Town, Rural
  • frpl_min / frpl_max — FRPL %
  • math_proficiency_min — Min math %
  • pps_min / pps_max — Per-pupil $
  • limit — Results (max 20, default 10)
compare_districts

Compare 2-5 school districts side by side with full profiles.

Parameters:
  • nces_ids — Array of 2-5 NCES IDs (required)
get_state_summary

Get aggregate education statistics for a US state — enrollment, districts, spending, proficiency rates.

Parameters:
  • state_code — 2-letter abbreviation (required)
list_districts_in_state

List all school districts in a state with summary data. Paginated (up to 50 per page).

Parameters:
  • state_code — 2-letter abbreviation (required)
  • cursor — Pagination cursor
  • limit — Results per page (max 50, default 20)

Example: Call a Tool

curl -X POST https://edusignal.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "lookup_district",
      "arguments": {
        "nces_id": "3704320"
      }
    },
    "id": 2
  }'

Rate Limits: The MCP server shares the same 10,000/day quota as the REST API. Each tool call counts as one request.

Claude Desktop Setup

Connect EduSignal directly to Claude Desktop to ask questions about K-12 school districts in natural language. Claude will use the MCP tools automatically.

Configuration

Add this to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "edusignal": {
      "url": "https://edusignal.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual API key. Restart Claude Desktop after saving the config.

Example Prompts

Once connected, try asking Claude:

"What's the enrollment and demographics of Wake County Public Schools in North Carolina?"

"Compare per-pupil spending between Los Angeles Unified and Chicago Public Schools."

"Find suburban districts in Texas with enrollment over 50,000 students."

"What are the math proficiency rates for the largest districts in California?"

Troubleshooting

  • Tools not appearing: Verify your API key is valid and the config JSON is properly formatted.
  • Rate limit errors: Wait for the daily quota to reset at midnight UTC.
  • Connection issues: Check that Claude Desktop can reach edusignal.ai (no VPN/firewall blocking).

Questions?

For API support, integration help, or feature requests, contact us at kevin@edusignal.ai

Need the complete dataset? View Bulk Data Export options