README.md

District Graphs API

🚧 Under Construction 🚧

Block equivalency files (BEFs) are a common file format used in legislative redistricting. They’re produced by software like DistrictBuilder, Maptitude, and Dave’s Redistricting App. The U.S. Census publishes nationwide district BEFs. To use a BEF in geospatial software, you first need to convert it from a list of (identifier, district) pairs to polygons. PlanScore’s experimental District Graphs API is here to help.

Try It

1. Find a BEF to experiment with. For example, Pennsylvania published their 2018 remedial U.S. House plan Census Block Equivalency File.

2. Get a pair of URLs from the District Graphs API. Use the layer parameter to specify a geographic subdivision to assign, one of tract (Census tract), bg (block group), or tabblock (Census block).

   HTTP GET https://dgraphs.planscore.org/upload_file?layer=tract
   

   Response:

   {
     "assignments_url": "https://districtgraphs.s3.amazonaws.com/assignments/...",
     "districts_url": "https://dgraphs.planscore.org/read_file?upload=..."
   }
   

3. Upload your BEF to the assignments_url:

   HTTP PUT {assignments_url}
   Body: Contents of equivalency file
   

4. Poll the districts_url URL until status is complete:

   HTTP GET https://dgraphs.planscore.org/read_file?upload=...
   

   Initial response:

   {
       "state": "started", "token": "...", "district_ids": [ ... ], "geojson_url": null
   }
   

   Again:

   HTTP GET https://dgraphs.planscore.org/read_file?upload=...
   

   Completed response:

   {
       "state": "complete", "token": "...", "district_ids": [ ... ],
       "geojson_url": "https://districtgraphs.s3.amazonaws.com/.../districts.geojson"
   }
   

   Example Pennsylvania response.

5. The geojson_url will contain a GeoJSON file with outlines for each legislative district which can be used in GIS software like ArcGIS and QGIS or uploaded to PlanScore to get its predicted partisan behavior.

6. If you’re editing your BEF you can re-use these same two URLs repeatedly. The assignments_url will be valid for re-use for approximately one hour.