MuniSpot REST API

Programmatic access to standardized financial statements, MuniScore and economic indicators for 20,000+ U.S. governments. Built from audited ACFRs and structured for institutional platforms, research tools and analytical workflows.

All requests need a valid API key, passed as a Bearer token in the Authorization header. Generate one in your account, or contact sales for enterprise access.

Intended use cases

Endpoints

Rate limits

For full plan details and annual billing, see Pricing.

Authentication

Every request must include your API key as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Example: cURL

curl "https://www.munispot.com/api/v1/entities?per_page=5" \
  -H "Authorization: Bearer ms_live_abc123..."

Example: Python

import requests

response = requests.get(
    "https://www.munispot.com/api/v1/entities",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"state": "CA", "per_page": 10}
)
data = response.json()

Keep your key secret. Never expose API keys in client-side code, public repositories or browser requests. Call the API from a server, and keep keys in environment variables.

Errors and rate limits

Every error response uses the same JSON envelope, so you can handle them in one place.

Response format

{
  "status": "success",
  "data": { ... },
  "meta": { ... }
}

{
  "status": "error",
  "code": 401,
  "message": "Invalid API key"
}

HTTP status codes

Rate limit behavior

Each API key has a monthly request quota (default 100) that resets on the 1st of each month, UTC. Past the limit, requests return 429 until the next reset.

Tip. Cache responses for governments that don't change often. Scores are recalculated monthly; financial data updates once per fiscal year.

Search and filter all municipalities. Returns paginated results with basic profile data. Use the municipality or scores endpoint for MuniScore data.

// Send a request to see a live response.

curl "https://www.munispot.com/api/v1/entities?state=WI&sector=city&fiscal_year=2024&per_page=2&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Full profile for one government: municipality information, every score component, individual metric values and a generated fiscal-year financial summary.

// Send a request to see a live response.

curl "https://www.munispot.com/api/v1/entities/396005924?fiscal_year=2023" \
  -H "Authorization: Bearer YOUR_API_KEY"

Scores only. Returns the composite score, four component scores with weights, and every metric value in a structured format. The response carries scorecard: for v5 the components are economy, budgetary, reserves and debt; for a utility (ut_v1) they are economy, system, liquidity and debt, the metrics are days_cash, dsc, debt_to_revenue (x), asset_condition_yrs and om_musd, and flags and factor_details record how each metric was read.

// Send a request to see a live response.

curl "https://www.munispot.com/api/v1/entities/396005924/scores?fiscal_year=2023" \
  -H "Authorization: Bearer YOUR_API_KEY"

Standardized financial line items from the government's ACFR (Annual Comprehensive Financial Report): balance sheet, income statement, reconciliation and long-term obligations.

// Send a request to see a live response.

curl "https://www.munispot.com/api/v1/entities/396005924/financials?fiscal_year=2023&statement_type=balance_sheet" \
  -H "Authorization: Bearer YOUR_API_KEY"

Data coverage

Sectors

Data dictionary: classifications

Every line item from Get financials carries a two-level classification. Source ACFRs label the same concept hundreds of ways; we map each line to a fixed taxonomy so property tax revenue, say, compares directly across all 20,000+ governments and every fiscal year.

The two fields

Despite the names, class_2 is the broad category and class_1 is the specific line item within it. Read them as a pair, scoped to statement_type. A class_1 value only has meaning inside its class_2.

Worked example

One property-tax row from a city income statement:

{
  "fiscal_year": 2023,
  "statement_type": "income_statement",
  "class_2": "REVENUES",
  "class_1": "PROPERTY TAX REVENUES",
  "column_index": 1,
  "value": 48217000
}

Categories by statement type

Valid class_2 values differ per statement. The most common are below. Rows whose class_2 begins with TOTAL or SUBTOTAL are pre-computed roll-ups, not detail lines.

Revenue line items class_2 = REVENUES

Expense line items class_2 = EXPENSES

Balance-sheet line items

Assets class_2 = ASSETS

Liabilities class_2 = LIABILITIES

Fund balance is reported through class_2, not class_1. The five GASB 54 classes (NONSPENDABLE, RESTRICTED, COMMITTED, ASSIGNED, UNASSIGNED) describe spending constraints from least to most flexible.

Business-type statements utilities and community colleges

Standalone utilities and community colleges publish proprietary (business-type) statements instead of governmental fund statements. For them the endpoint returns these statement types only; governments never return them. Values are dollars as printed. class_1 is the standardized line class, or null for detail and subtotal lines; class_2 is null except on bta_coverage. column_index 1 to n are the columns in page order (one per system, e.g. Electric, Gas, Water), and -1 is a printed total column when the audit prints one.

Several lines can share a class_1 (three INVESTMENTS lines, or a line and its total). For one figure per class, take the last line of the class whose label contains “total”, else the sum of the class's lines; never sum lines whose class_1 is null. When a utility prints several systems and no total column, there is no printed combined figure: any sum across columns is computed.

Debt instrument types statement_type = long_term_obligations

For long-term obligations the instrument type is in class_1 and the roll-forward column is in class_2. For year-end debt, filter class_2 = ENDING_BALANCE.

Working with classifications

Need the full enumerated list to map against your current provider? The sandbox starter kit ships a machine-readable classification reference and an audit notebook that reports line-item match rate against ACFR source.

MuniSpot for institutions

Standardized ACFR financials, scoring and economic indicators through the same REST and MCP interfaces single developers use, with the contract terms, refresh commitments and integration support institutional teams need.

Already evaluating? Skip to Sandbox and evaluation for a structured side-by-side data-quality test against your current provider.

Who this is for

What enterprise customers get

• Unlimited requestsNo monthly cap and no per-EIN daily limit. Predictable for batch workloads.
• All 4 REST endpoints and MCPIncluding /financials (ACFR line items, not gated).
• Multi-seat key managementUp to 10 keys per account, per-seat usage attribution, rotation without downtime.
• Bulk extracts and scheduled snapshotsOn request: full-universe Parquet or CSV drops to S3 or GCS.
• Webhooks (roadmap)Notifications on MuniScore changes, new fiscal-year availability or watchlist events.
• Redistribution rightsNegotiated terms for embedding MuniSpot data in client-facing dashboards or research products.
• SLA and dedicated supportUptime commitment, Slack channel, named technical contact.

Next steps

Integration patterns

Four patterns we see in institutional deployments. Pick the one closest to your stack, or combine them. All four use the same REST and MCP interfaces documented here, on the same api/v1 base.

AWarehouse sync

Scheduled ELT into Snowflake, BigQuery or Postgres. The most common pattern for buy-side credit teams. A nightly job pulls /entities for the universe, then iterates per issuer for /scores and /financials, landing rows in your own tables.

import requests, time
from datetime import date

HEADERS = {"Authorization": f"Bearer {API_KEY}"}
BASE = "https://www.munispot.com/api/v1"

def sync_universe(state, fiscal_year):
    page, rows = 1, []
    while True:
        r = requests.get(f"{BASE}/entities", headers=HEADERS,
                         params={"state": state, "per_page": 50, "page": page,
                                 "fiscal_year": fiscal_year})
        body = r.json()
        rows.extend(body["data"])
        if len(rows) >= body["meta"]["total"]: break
        page += 1
    return rows

def sync_scores(ein, fiscal_year):
    r = requests.get(f"{BASE}/entities/{ein}/scores", headers=HEADERS,
                     params={"fiscal_year": fiscal_year})
    return r.json()["data"] if r.status_code == 200 else None

# Run nightly; write to warehouse via your loader of choice

BOn-demand lookup from internal apps

An internal credit dashboard or research portal calls MuniSpot per issuer at view time. Best for low-volume, interactive use where freshness matters more than batch efficiency. Cache aggressively: scores recompute monthly, line items annually.

Caching guideline. 24-hour cache on /scores, 7-day cache on /financials, no cache on user-driven searches.

CMCP server for analyst workflows

Point Claude Desktop, Cursor or any MCP client at https://www.munispot.com/api/mcp with your enterprise key. Analysts ask questions in plain language and the agent calls MuniSpot tools without anyone writing HTTP code. Common on credit research desks doing quick comparisons.

See the full MCP setup guide for client-specific configuration.

DBulk extract (on request)

For backtests, model training or large universe scans where REST round-trips are inefficient. We deliver point-in-time Parquet or CSV drops of the full universe, or a custom slice, to your S3 or GCS bucket on your cadence. Enterprise tier only.

Reliability and retry guidance

• GETs are idempotent and safe to retry on network errors.
• Back off exponentially on 429 (rate limit) and 5xx.
• Enterprise keys have no monthly cap; per-second burst limits still apply.
• The schema is versioned by the /v1 path. Breaking changes ship as /v2 with a six-month overlap.

Data refresh and coverage

When each data type updates, where it comes from, and the coverage to expect across the universe.

Refresh cadence

Coverage

Coverage by sector

MuniSpot covers four core sectors. Special districts (water, fire, transit and so on) are in the database but excluded from the public catalog by default; available by enterprise contract.

• Cities and municipalities, including towns, villages and boroughs
• Counties
• K-12 school districts
• State governments

Freshness signal

Every municipality response includes a fiscal year and a confidence badge based on how many of the 9 underlying metrics were available for that filing. Use the badge to gate downstream decisions when freshness or completeness matters.

Security and compliance

What you need for procurement and legal review. For full attestation packets and DPA negotiation, contact sales.

API security

• All traffic over TLS 1.2 or later. Plain HTTP requests are refused.
• API keys are stored hashed; only a prefix and fingerprint are visible after creation.
• Key rotation is self-serve from your account, without integration downtime.
• Per-key audit log of creation, rotation, revocation and usage events.
• Each response carries a key fingerprint, so a key shared in error can be traced internally.

Data source and provenance

MuniSpot is built only from public-record sources: issuer-published Annual Comprehensive Financial Reports (ACFRs), federal datasets (Census, BLS, BEA, FHFA, NCES) and the Federal Audit Clearinghouse. We do not use MSRB EMMA-restricted material, broker-dealer feeds or any non-public channel. Every as-reported line item is kept alongside our normalized version so you can reconcile to source.

Redistribution and licensing

Default API terms permit internal use only. Redistribution, meaning MuniSpot data in client-facing dashboards, research products or publications, needs an enterprise contract with explicit redistribution rights. Three patterns we support:

• Internal onlyThe default. Use in your own apps, dashboards, models and research.
• Attributed embedShow data in client-facing products with required attribution.
• White labelEmbed without attribution under negotiated terms.

SLA and support

Enterprise contracts include a written SLA. Default targets:

• 99.5% uptimeOn the REST API and MCP server.
• P95 latency under 500 msOn municipality and score endpoints.
• Email and Slack supportResponse times by severity.
• Named technical contactFor integration support and incident handling.

Procurement documents. If your security or legal team needs a vendor questionnaire, DPA or attestation packet, request it from contact sales.

Sandbox and evaluation

A structured way to test MuniSpot against your current municipal data provider. We provision a time-bounded enterprise key, hand you a starter kit, and walk through a side-by-side data-quality comparison.

Status. During early access the sandbox is provisioned by hand. Request access from Contact sales and we reply within one business day.

What's in the starter kit

• Time-bounded enterprise API keyTwo-week key with unlimited requests and no per-EIN daily cap, scoped to your evaluation universe.
• Postman or Insomnia collectionPre-wired requests for every endpoint, with sample EINs across cities, counties, school districts and states.
• Two Jupyter notebooks, Colab-readyA quickstart (key to dataframes in minutes) and a data-quality audit comparing coverage, freshness, line-item match rate and score correlation with your current provider.
• MCP server configDrop-in JSON for Claude Desktop, Cursor or Gemini CLI to query MuniSpot in plain language during evaluation.
• Sample SQLMaterialized-view definitions for landing MuniSpot data in Snowflake or BigQuery.

Quickstart notebooks

Two runnable notebooks. Open them in Google Colab with no local setup, or download and run anywhere. Your API key is entered at runtime with getpass, so it is never written into the file.

To run in Colab: open colab.research.google.com, choose File, Upload notebook, and select the downloaded file.

Recommended evaluation steps

1. Pick 25 to 50 issuers you know well: a mix of large GO issuers, mid-size cities, school districts and at least one distressed name.
2. Run the audit notebook against both providers. It reports coverage, freshness (latest fiscal year available), line-item match rate against ACFR source, and score correlation if your current provider has scores.
3. Spot-check 3 to 5 issuers by opening the source ACFR and comparing line items in both providers to the published statement.
4. Try the MCP server in Claude Desktop with one of your credit analysts. Ask the questions you'd normally ask an associate.
5. Review the schema against your warehouse model to find joins, naming gaps and missing fields.

Try it live now

Every endpoint above has a Try it panel that calls the production API with your key. While we provision your sandbox kit, you can check the shape of every response in your browser:

Contact sales

For enterprise pricing, sandbox provisioning, contract terms, redistribution rights or technical onboarding.

What to include in your message

• Your firm and roleSo we route you to the right technical contact.
• Use caseInternal credit workflow, client dashboard, research product, model input and so on.
• VolumeRough number of issuers in scope and expected request cadence.
• Integration targetWarehouse (Snowflake, BigQuery and so on), BI tool or app stack.
• Redistribution needsInternal only, attributed embed or white label.
• TimelineWhen you'd like to be in production.

Already have a key? Start now: the Try it panels on every endpoint call the real API with your key. Get in touch when you're ready for enterprise terms or a sandbox kit.