canonical: https://jentic.com/apis/planscore.org/planscore

# PlanScore API

The PlanScore API scores electoral district plans for partisan fairness and returns a machine-readable index alongside a web page of graphs and maps. Small plans go up directly as a GeoJSON FeatureCollection of district polygons under 5MB, each optionally tagged with an Incumbent value of R, D, or O; larger files and shapefiles use a multistep flow that hands back pre-signed S3 upload fields and is finished with a call that adds incumbents, vote swings, and a model version. Existing plans can be re-scored against a newer predictive model, and temporary uploads and re-scores disappear within a week. The vendor marks the API as under development.

## For AI agents

Upload a redistricting plan as GeoJSON or a shapefile, score it with PlanScore's predictive model, and get back an index_url and a plan_url with the results. Re-score plans against newer model versions and list supported states and models.

## Scope

Does not handle voter registration, election results, or drawing district boundaries. Use for scoring uploaded electoral district plans only.

## Capabilities

- Score a GeoJSON district plan for partisan fairness by uploading a FeatureCollection of Polygon or MultiPolygon districts
- Upload larger plans or shapefiles through pre-signed S3 upload fields, then finish with incumbents, vote_swings, and a model_version
- Re-score an existing plan by its id against the latest predictive model or with an updated description
- Run temporary scoring for drafts whose results disappear within a week
- List the states and legislative bodies PlanScore can score, and the predictive model versions available
- Attach library_metadata such as an authoritative_link or predecessor_link so a plan page cites its source

## Use cases

### Agent-Driven Redistricting Analysis via Jentic

An AI agent supporting a redistricting researcher or journalist takes a proposed map, checks that the state is supported, and uploads it for scoring. Through Jentic the agent calls the PlanScore upload operation with the GeoJSON plan and returns the plan_url for the graphs and maps plus the index_url for machine-readable results, without the researcher wiring the bearer token or the S3 upload steps.

Example prompt: Call GET /states to confirm TX congress is supported, then upload a TX congressional GeoJSON plan with POST /upload and return its plan_url and index_url

### Comparing Draft Redistricting Plans

Advocacy groups and legislative staff testing alternative maps submit each draft through the temporary upload so results expire within a week instead of joining the permanent library. Tagging each district's Incumbent property as R, D, or O improves the predictions, and each draft returns its own plan page for side-by-side review.

Example prompt: Upload three draft state house plans with POST `/upload/temporary`, each with Incumbent tags on every district, and collect the three plan_url values

### Re-Scoring Enacted Plans with New Models

When PlanScore publishes a new predictive model, analysts re-run enacted plans to keep published figures current. The clone operation takes the existing plan id and an optional model_version and description, and plans shared with PlanScore are kept indefinitely, so the re-score sits next to the original.

Example prompt: List model versions with GET /model_versions, then call POST /clone with plan id 20210307T032912.752515089Z and the newest model_version and return the new plan_url

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/upload` | Upload a GeoJSON district plan for scoring |
| GET | `/upload` | Get pre-signed S3 upload fields |
| POST | `/uploaded` | Complete a multistep upload and start scoring |
| POST | `/clone` | Re-score an existing plan |
| POST | `/upload/temporary` | Score a temporary plan |
| GET | `/states` | List supported states and legislative bodies |
| GET | `/model_versions` | List predictive model versions |

## Key resources

- **Plans** — Upload GeoJSON plans directly or temporarily, and receive index_url and plan_url results.
- **Multistep uploads** — Request pre-signed S3 upload fields, upload the file, and complete the upload with incumbents, vote swings, and model version.
- **Clones** — Re-score an existing plan by id, permanently or temporarily.
- **Reference data** — Supported states and legislative bodies, and available predictive model versions.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 54 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 90 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 28 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/planscore.org/planscore/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring PlanScore by hand means requesting a bearer token by email, choosing between direct GeoJSON upload and the pre-signed S3 multistep flow, and posting the completion call with incumbents and model version. Through Jentic you install once, import PlanScore from the API Directory, store the token once, and your agent scores plans.
- **Permission scoping:** PlanScore carries the plan id in the request body rather than the URL path, so rules bound which operations your agent may call, not which plan. You choose the operations it may call, so permanent uploads and re-scores are not included unless you add them.
- **Credential handling:** Your PlanScore bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'score a redistricting plan' or 're-score a district map', and Jentic returns the matching PlanScore operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **US Census Bureau** — The Census API supplies population and demographic data by geography; PlanScore scores the district boundaries drawn over it.
- **Open States** — Open States covers state legislators, bills, and districts; PlanScore scores proposed district maps.
- **Mapbox** — Mapbox renders and analyses custom map data in general; PlanScore is purpose-built for scoring electoral district plans.

## FAQ

### What authentication does the PlanScore API use?

The PlanScore API uses bearer authentication per its OpenAPI spec: send your token in an Authorization: Bearer header. Tokens are issued on request by emailing info@planscore.org. The spec applies the bearer scheme at the top level, and describes the browser upload fields operation as intended for direct browser use. Through Jentic the token is stored encrypted on your own instance and injected at call time.

### Is there a PlanScore MCP server?

You don't need an MCP server to give your agent PlanScore. Jentic connects it directly from the API Directory: import PlanScore, store your bearer token once, and your agent can upload and score district plans straight away. Operations are discovered on demand, so no extra server's tool definitions sit in your agent's context.

### Can I limit what my agent is allowed to do with the PlanScore API?

Yes. Write a rule that allows only the temporary upload, temporary clone, and states operations, so the agent can score drafts whose results expire within a week but cannot add plans to the permanent library, and every call it makes is logged.

### How do I upload a plan larger than 5MB to PlanScore?

Use the multistep flow. Call GET /upload for a pre-signed S3 URL and form fields, post the file to S3, then call POST /uploaded with the redirect from S3 plus an optional description, incumbents list, vote_swings, and model_version to start scoring. The same flow handles shapefiles.

### What are the rate limits for the PlanScore API?

The PlanScore OpenAPI spec does not specify rate limits, and the vendor marks the API as under development. Ask info@planscore.org about usage limits when you request a token.

### How do I score a district plan with the PlanScore API through Jentic?

Search Jentic for an intent like 'score a redistricting plan', import PlanScore, and store your bearer token once. Your agent then calls POST /upload with a GeoJSON FeatureCollection of districts and reads the plan_url and index_url from the response. To run it on your own infrastructure, install Jentic One from its GitHub repo.