{ "openapi": "3.1.0", "info": { "title": "CCA Community API", "version": "0.9.0", "summary": "Census geography and tract-level community conditions API", "description": "Resolve U.S. locations to a normalized Census geography hierarchy and retrieve a cached, source-attributed tract bundle spanning ACS, CDC PLACES, CDC SVI, EPA EJScreen, FEMA NRI, and USDA Food Access. Area-scale ERA5 reanalysis statistics and climate normals come from cca-weather. Nearby schools, aviation landing facilities, religious organizations, violence-event statistics, and IRS exempt organizations are assembled from sibling CCA APIs exclusively through Cloudflare service bindings, with exact USPS PO Box host facilities delegated to cca-postalfacilities and labeled as mailing rather than operating locations. normalized GeoJSON and conservative entity resolution so generic IRS records supplement rather than duplicate matching school or religious-organization pointers. Immutable raw FCC Broadband Data Collection public files are cataloged in D1 and mirrored to R2. Every JSON response uses the CCA fleet envelope. Batch reads are cache-only and bounded so one client request cannot amplify into many public upstream calls. Anonymous public reads can be answered from Workers Cache: X-Public-Cache reports HIT, MISS, STALE, UPDATING, BYPASS, or ERROR; X-Public-Cache-Generated-At and Age tell how old the body is; X-Request-Id is fresh on every delivery while meta.request_id identifies the generating request.", "contact": { "name": "Cooperative Computing Alliance", "url": "https://coopalliance.org" } }, "servers": [ { "url": "https://community.datasourceapi.com/api/v1" } ], "security": [], "tags": [ { "name": "Service", "description": "Health, operational status, coverage, and source discovery." }, { "name": "Geography", "description": "Address, ZIP, and coordinate resolution through Census services." }, { "name": "Tracts", "description": "Single, sliced, listed, and bounded batch tract reads." }, { "name": "Reports", "description": "Branded single-location and comparison PDF reports." }, { "name": "Layers", "description": "Nearby CCA schools, aviation facilities, religious organizations, violence, and exempt-organization data layers." }, { "name": "Climate", "description": "Area-scale recent weather statistics and long-term climate normals from CCA Weather." }, { "name": "Broadband", "description": "FCC BDC release catalogs and immutable R2-mirrored files." }, { "name": "Tiles", "description": "Self-hosted Census boundary vector tiles from R2 PMTiles archives." }, { "name": "Admin", "description": "Operational mutations protected by X-Admin-Key." } ], "paths": { "/health": { "get": { "tags": [ "Service" ], "summary": "Lightweight runtime and required-binding health", "operationId": "getHealth", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "The D1 binding is missing or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/report": { "get": { "tags": [ "Reports" ], "summary": "Generate a PDF community report (single location, or a comparison of up to 5)", "operationId": "getCommunityReport", "description": "Renders the full geography hierarchy + all six SDOS sources as a branded PDF. Selected live CCA layers can add summaries, every unique record returned by the bounded request, rich aviation terminology, runway/frequency detail, and colored points on the site map. Callers choose nearby radius, result cap, summary/list depth, aviation enrichment, and map depth. Repeat q up to 5 times for a landscape side-by-side comparison. A fan-out budget rejects combinations that would make too many sibling-service and map calls instead of silently dropping data. Every page carries the official Cooperative Computing Alliance logo/name, correlation ID, human-readable UTC generation time, and \"Page X of Y\"; an authoritative copy is archived to R2 and recorded in the reports ledger before the response is served. The correlation ID is returned in the X-Correlation-Id response header. Aggregate ZIP PDFs are never emitted partially: while intersecting tracts are warming, the endpoint returns ERROR_AGGREGATE_PREPARING with Retry-After.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "style": "form", "explode": true, "description": "Location: street address, City/State, 5-digit ZIP (ZIP+4 ok), or \"lat,lon\". Repeatable (2-5 → comparison report)." }, { "name": "tract", "in": "query", "schema": { "type": "array", "items": { "type": "string", "pattern": "^(?:\\d{11})?$" }, "maxItems": 5 }, "style": "form", "explode": true, "description": "Selected tract GEOID for each q. Required when a ZIP or city/state locality intersects multiple tracts; repeat once per q and use an empty value for locations without a tract scope." }, { "name": "vintage", "in": "query", "schema": { "type": "string" }, "description": "TIGERweb vintage (default ACS2025)" }, { "name": "acs_year", "in": "query", "schema": { "type": "string" }, "description": "ACS vintage for the data bundle" }, { "name": "layers", "in": "query", "schema": { "type": "string", "default": "all" }, "description": "Comma-separated live layers: schools, aviation-facilities, religious-organizations, violence, exempt-organizations. Use all or none." }, { "name": "layer_radius_km", "in": "query", "schema": { "type": "number", "minimum": 0.1, "maximum": 80, "default": 25 }, "description": "Straight-line nearby radius for selected live layers." }, { "name": "layer_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Maximum returned records per selected layer; aviation-facilities remains capped at 25 by its source contract." }, { "name": "layer_detail", "in": "query", "schema": { "type": "string", "enum": [ "summary", "lists" ], "default": "lists" }, "description": "Include summaries only or complete unique lists of every record returned by each bounded layer request." }, { "name": "aviation_details", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "When aviation lists are included, request each nearest facility with its mirrored runway and published radio-frequency details." }, { "name": "climate", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Include recent ERA5 reanalysis statistics plus monthly/annual climate normals." }, { "name": "broadband", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Include FCC Broadband Data Collection availability from cca-broadband: the smallest containing area with its county and state for one location, or each location's county in comparisons. When omitted it is included only if it fits the report budget; an explicit true is strict." }, { "name": "climate_stats_years", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Recent complete/recent period length ending seven days before report generation." }, { "name": "climate_normal_start_year", "in": "query", "schema": { "type": "integer", "minimum": 1940, "default": 1991 } }, { "name": "climate_normal_end_year", "in": "query", "schema": { "type": "integer", "default": 2020 }, "description": "Baseline must span 10-50 complete years." }, { "name": "report_maps", "in": "query", "schema": { "type": "string", "enum": [ "none", "site", "all" ], "default": "site" }, "description": "No maps, a site/scope map with selected live-layer points, or (single-location reports only) the site map plus every available civic boundary inset." } ], "responses": { "200": { "description": "application/pdf (X-Correlation-Id header)", "content": { "application/pdf": {} } }, "400": { "description": "Invalid report query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "One or more locations could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "A ZIP requires tract selection, or an aggregate PDF is still preparing all intersecting tracts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Report generation or archival failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Census geography services could not resolve a safe tract context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Report archive, assets, database, or MAPS service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/climate": { "get": { "tags": [ "Climate" ], "summary": "Combined recent weather statistics and long-term climate normals", "description": "Calls cca-weather exclusively through the WEATHER service binding, validates both contracts, and caches the assembled profile in KV for six hours. Components degrade independently. Values are ERA5/ERA5-Land seamless modeled reanalysis for an area-scale grid cell, not one station.", "operationId": "getClimateProfile", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "stats_start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Defaults to stats_years before the safe recent end date." }, { "name": "stats_end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Defaults to seven days before generation to remain behind ERA5 lag." }, { "name": "stats_years", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "none", "month", "year" ], "default": "year" } }, { "name": "normal_start_year", "in": "query", "schema": { "type": "integer", "minimum": 1940, "default": 1991 } }, { "name": "normal_end_year", "in": "query", "schema": { "type": "integer", "default": 2020 }, "description": "Normal baseline must span 10-50 complete years." } ], "responses": { "200": { "description": "Combined climate profile with statistics, normals, glossary, coverage, provenance, and limitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Upstream or edge rate limit exceeded; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "504": { "description": "CCA Weather timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/climate/stats": { "get": { "tags": [ "Climate" ], "summary": "Recent/custom-period ERA5 climate statistics", "operationId": "getClimateStatistics", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "stats_start_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "stats_end_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "stats_years", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "none", "month", "year" ], "default": "year" } } ], "responses": { "200": { "description": "Period summary and flattened monthly/yearly series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Upstream or edge rate limit exceeded; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "504": { "description": "CCA Weather timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/climate/normals": { "get": { "tags": [ "Climate" ], "summary": "Long-term monthly and annual ERA5 climate normals", "operationId": "getClimateNormals", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "normal_start_year", "in": "query", "schema": { "type": "integer", "minimum": 1940, "default": 1991 } }, { "name": "normal_end_year", "in": "query", "schema": { "type": "integer", "default": 2020 }, "description": "Baseline must span 10-50 complete years." } ], "responses": { "200": { "description": "Annual normal, twelve monthly normal blocks, highlights, coverage, and source metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Upstream or edge rate limit exceeded; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "504": { "description": "CCA Weather timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/status": { "get": { "tags": [ "Service" ], "summary": "Bindings, cache coverage, source catalog, and supported cycles", "operationId": "getStatus", "parameters": [ { "name": "summary", "in": "query", "description": "Return only lightweight coverage totals instead of per-source and per-state detail.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Service status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/sources": { "get": { "tags": [ "Service" ], "summary": "List every geography and tract data source", "operationId": "listSources", "responses": { "200": { "description": "Source catalog", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "count", "sources" ], "properties": { "count": { "type": "integer" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } } } } ] } } } } } } }, "/sources/{source}": { "get": { "tags": [ "Service" ], "summary": "Get one source definition by id or slice", "operationId": "getSource", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Canonical source id or short slice name.", "schema": { "type": "string" }, "examples": { "slice": { "value": "health" }, "canonical": { "value": "cdc-places" } } } ], "responses": { "200": { "description": "Source definition", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Source" } } } ] } } } }, "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/coverage": { "get": { "tags": [ "Service" ], "summary": "Cached tract coverage and freshness by source and state", "operationId": "getCoverage", "description": "Returns D1-only aggregate counts. `missing` means no payload is cached; `stale` means a source was attempted but its freshness window has elapsed.", "responses": { "200": { "description": "Coverage report", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "tracts", "states", "counties", "sources", "by_state" ], "properties": { "tracts": { "type": "integer" }, "states": { "type": "integer" }, "counties": { "type": "integer" }, "sources": { "type": "object", "additionalProperties": { "type": "object" } }, "by_state": { "type": "array", "items": { "type": "object" } } } } } } ] } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/geocode/suggest": { "get": { "tags": [ "Geography" ], "summary": "Get ranked address, locality, and postal suggestions", "operationId": "suggestLocations", "description": "Proxies the bounded cca-geocode autocomplete/correction contract through the GEOCODE service binding, forwarding the client abort signal (cancellations return an empty 499). Suggestions retain explicit precision, provenance, confidence, and search-origin/feature suitability plus response-level safe_to_submit and ambiguity. User-facing locality text omits legal Census suffixes while authoritative_label preserves them; ambiguous places are never silently selected.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Partial or misspelled address, locality, or postal query (2–160 characters).", "schema": { "type": "string", "minLength": 2, "maxLength": 160 }, "example": "Newtownn, CT" }, { "name": "limit", "in": "query", "description": "Maximum ranked suggestions.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 8 } } ], "responses": { "200": { "description": "Normalized ranked suggestions and explicit correction metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/geographies": { "get": { "tags": [ "Geography" ], "summary": "Resolve exactly one address/locality, ZIP, or coordinate pair", "operationId": "resolveGeographies", "description": "Exactly one location form is required. ZIP/ZCTA results include every tract whose interior intersects the ZCTA; the centroid tract is identified separately and is not treated as the ZIP's only tract. City/state locality results likewise include every tract intersecting the authoritative Census place or county-subdivision polygon. Add `include=data` to retrieve a selected tract bundle. For a ZIP or locality with multiple tracts, pass the explicit `tract` GEOID, or use `include=aggregate` for source-aware combined statistics across every intersecting tract. Aggregate counts are summed while rates and tract medians are population-weighted with explicit coverage metadata. City/state input uses the bound cca-geocode place resolver and preserves explicit centroid precision/suitability. `sources` limits which upstreams may refresh and which source columns are returned.", "parameters": [ { "name": "address", "in": "query", "description": "One-line U.S. street address or city/town plus state, at most 500 characters.", "schema": { "type": "string", "maxLength": 500 }, "example": "1600 Pennsylvania Ave NW, Washington, DC 20500" }, { "name": "zip", "in": "query", "description": "5-digit ZIP/ZCTA or ZIP+4; ZIP+4 is resolved using its ZIP5.", "schema": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" }, "example": "20500" }, { "name": "tract", "in": "query", "description": "11-digit tract GEOID selected from a ZIP response. Valid only for ZIP lookups.", "schema": { "type": "string", "pattern": "^\\d{11}$" }, "example": "06081607600" }, { "name": "lat", "in": "query", "description": "Latitude; must be paired with lon.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "description": "Longitude; must be paired with lat.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "vintage", "in": "query", "description": "Census TIGERweb service vintage.", "schema": { "type": "string", "pattern": "^ACS20\\d{2}$", "default": "ACS2025" } }, { "name": "include", "in": "query", "description": "Comma-separated expansions: `data` appends one selected `tract_data`; `aggregate` appends combined cached data for all intersecting ZIP or city/state locality tracts and queues incomplete tracts; `layers` appends nearby CCA data layers; `climate` appends recent ERA5 statistics and long-term normals for the resolved point; `broadband` appends FCC Broadband Data Collection availability from cca-broadband for the place, county, metro area, and state containing the resolved point (the selected tract when a ZIP or city search selects one) (area-level, not per-address).", "schema": { "type": "string", "examples": [ "data,climate,broadband", "aggregate,climate", "layers,climate,broadband" ] } }, { "name": "sources", "in": "query", "description": "Comma-separated source ids or slices. Accepted slices: acs, health, svi, environment, risk, food.", "schema": { "type": "string" }, "example": "acs,health,svi" }, { "name": "acs_year", "in": "query", "description": "The configured default vintage is cached; historical vintages are request-local.", "schema": { "$ref": "#/components/schemas/AcsYear" } }, { "name": "warm", "in": "query", "description": "With include=aggregate, queue incomplete ZIP/locality tracts for background refresh. Set false while polling.", "schema": { "type": "boolean", "default": true } }, { "name": "layer_radius_km", "in": "query", "description": "Nearby search radius when include contains layers.", "schema": { "type": "number", "minimum": 0.1, "maximum": 80, "default": 25 } }, { "name": "layer_limit", "in": "query", "description": "Maximum mapped records returned by each CCA data layer.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "aviation_details", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "When include contains layers, embed full runway/frequency details for each returned aviation facility in the single AEROSPACE call." }, { "name": "climate_stats_years", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "climate_stats_start_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "climate_stats_end_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "climate_group_by", "in": "query", "schema": { "type": "string", "enum": [ "none", "month", "year" ], "default": "year" } }, { "name": "climate_normal_start_year", "in": "query", "schema": { "type": "integer", "minimum": 1940, "default": 1991 } }, { "name": "climate_normal_end_year", "in": "query", "schema": { "type": "integer", "default": 2020 } }, { "name": "fields", "in": "query", "description": "Comma-separated top-level response fields to retain.", "schema": { "type": "string" }, "example": "tract_geoid,tract_name,acs_data,updated_at" } ], "responses": { "200": { "description": "Normalized geography hierarchy, ZIP tract intersections, and optional selected tract bundle", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GeographyResolution" } } } ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Ambiguous locality; specify a state or choose a returned candidate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tracts": { "get": { "tags": [ "Tracts" ], "summary": "List cached tracts with source availability", "operationId": "listCachedTracts", "description": "Lists only rows already in the community D1 cache. This endpoint never calls an upstream source.", "parameters": [ { "name": "state", "in": "query", "description": "2-digit state FIPS.", "schema": { "type": "string", "pattern": "^\\d{2}$" } }, { "name": "county", "in": "query", "description": "3-digit county FIPS or 5-digit state+county GEOID.", "schema": { "type": "string", "pattern": "^(\\d{3}|\\d{5})$" } }, { "name": "source", "in": "query", "description": "Require cached data from exactly one source id or slice.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "ISO 8601 lower bound on the tract row update time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "geoid", "updated" ], "default": "geoid" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated cached tract summaries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "tracts", "pagination", "filters" ], "properties": { "tracts": { "type": "array", "items": { "$ref": "#/components/schemas/TractBundle" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "filters": { "type": "object" } } } } } ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tracts/batch": { "post": { "tags": [ "Tracts" ], "summary": "Read up to 25 cached tracts in one request", "operationId": "batchCachedTracts", "description": "Cache-only by design: missing GEOIDs are returned in `data.missing` and are not fetched from public upstreams. Duplicate GEOIDs are removed while preserving first-seen order.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "geoids" ], "additionalProperties": false, "properties": { "geoids": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string", "pattern": "^\\d{11}$" } }, "sources": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 6 } ] }, "fields": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] } } }, "example": { "geoids": [ "11001980000", "06081601000" ], "sources": [ "acs", "health" ], "fields": [ "tract_geoid", "tract_name", "acs_data", "places_data" ] } } } }, "responses": { "200": { "description": "Ordered cached tract results and missing GEOIDs", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "requested", "found", "missing", "tracts", "duplicates_removed" ], "properties": { "requested": { "type": "integer" }, "found": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "string", "pattern": "^\\d{11}$" } }, "tracts": { "type": "array", "items": { "$ref": "#/components/schemas/TractBundle" } }, "duplicates_removed": { "type": "integer" } } } } } ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "415": { "description": "Content-Type is not application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/broadband/choropleth": { "get": { "tags": [ "Broadband" ], "summary": "FCC BDC coverage for every county or state, keyed by GEOID, for map shading", "description": "One percentage per county (or state) from cca-broadband through the BROADBAND service binding, keyed by the GEOID the /map-boundaries tiles carry. Values describe whole areas, not addresses. `bands` lists the lower bounds of the fair, good, and best shading bands the explorer uses. Edge-cached as reference data; the FCC file mirror under /broadband is never cached.", "operationId": "getBroadbandChoropleth", "parameters": [ { "name": "metric", "in": "query", "schema": { "type": "string", "enum": [ "terrestrial", "served", "fiber", "gigabit" ], "default": "terrestrial" }, "description": "`terrestrial`: Fixed 100/20 Mbps, wired or fixed wireless; satellite excluded; `served`: Fixed 100/20 Mbps, any technology including satellite; `fiber`: Fiber at 100/20 Mbps; `gigabit`: Any technology at 1000/100 Mbps." }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "county", "state" ], "default": "county" } } ], "responses": { "200": { "description": "Coverage percentage (0-100) per GEOID with the FCC release it came from", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "metric", "geography_kind", "count", "values", "bands" ], "properties": { "metric": { "type": "string" }, "label": { "type": "string" }, "geography_kind": { "type": "string", "enum": [ "county", "state" ] }, "count": { "type": "integer", "minimum": 1 }, "values": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } }, "bands": { "type": "array", "items": { "type": "number" } }, "report_url_template": { "type": "string" } } } } } ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "cca-broadband failed or returned an unusable choropleth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "504": { "description": "cca-broadband timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/broadband/releases": { "get": { "tags": [ "Broadband" ], "summary": "List FCC BDC releases and mirror completeness", "operationId": "listBroadbandReleases", "responses": { "200": { "description": "Availability, challenge, and Funding Map release summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/broadband/files": { "get": { "tags": [ "Broadband" ], "summary": "Search the mirrored FCC BDC file catalog", "operationId": "listBroadbandFiles", "parameters": [ { "name": "data_type", "in": "query", "schema": { "type": "string", "enum": [ "availability", "challenge", "funding", "funding_readme", "funding_geography" ] } }, { "name": "as_of_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "subcategory", "in": "query", "schema": { "type": "string" } }, { "name": "technology_type", "in": "query", "schema": { "type": "string" } }, { "name": "state_fips", "in": "query", "schema": { "type": "string", "pattern": "^\\d{2}$" } }, { "name": "provider_id", "in": "query", "schema": { "type": "string" } }, { "name": "representation", "in": "query", "schema": { "type": "string", "enum": [ "archive", "shapefile", "geopackage", "pdf", "csv" ] } }, { "name": "mirror_status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "downloading", "stored", "failed" ] } }, { "name": "include_withdrawn", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated FCC BDC file metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/broadband/files/{id}": { "get": { "tags": [ "Broadband" ], "summary": "Get FCC BDC file metadata and its original catalog record", "operationId": "getBroadbandFile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "FCC BDC file metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/broadband/files/{id}/download": { "get": { "tags": [ "Broadband" ], "summary": "Stream an immutable FCC BDC file from the R2 mirror", "operationId": "downloadBroadbandFile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "example": "bytes=0-1048575" } ], "responses": { "200": { "description": "Complete raw FCC file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Byte range of the raw FCC file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "File is cataloged but has not been mirrored yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "416": { "description": "Requested byte range is unsatisfiable" }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } }, "head": { "tags": [ "Broadband" ], "summary": "Inspect immutable FCC BDC file metadata", "operationId": "headBroadbandFile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Mirrored object headers" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "File is cataloged but has not been mirrored yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/layers": { "get": { "tags": [ "Layers" ], "summary": "List CCA data layers and service-binding availability", "operationId": "listDataLayers", "responses": { "200": { "description": "Data layer catalog and binding availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/layers/nearby": { "get": { "tags": [ "Layers" ], "summary": "Get combined nearby schools, aviation facilities, religious organizations, violence data, and exempt organizations", "description": "Domain-specific school and religious-organization records outrank matching generic IRS records. Conservatively matched exempt records are attached as supplemental metadata and do not emit a second pointer. Exact USPS PO Box hosts may emit mailing-facility points through the POSTAL service binding; coordinate-only bounded requests resolve up to 16 distinct PO Box ZIPs found in their exempt-organization rows. These points are excluded from proximity identity and violence-stack evidence. Violence events remain distinct records; events within 200 meters of an organization are represented as visual map stacks with an explicit no-involvement warning.", "operationId": "getNearbyDataLayers", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "radius_km", "in": "query", "schema": { "type": "number", "minimum": 0.1, "maximum": 80, "default": 25 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "state", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "zip", "in": "query", "schema": { "type": "string", "pattern": "^\\d{5}$" }, "description": "Enables verified ZIP-level violence analytics." }, { "name": "city", "in": "query", "schema": { "type": "string", "maxLength": 160 } }, { "name": "aviation_details", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Embed full aviation facility details in returned aviation items." } ], "responses": { "200": { "description": "Normalized report and map layers; unavailable bindings are explicit per layer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/layers/{layer}": { "get": { "tags": [ "Layers" ], "summary": "Get one nearby CCA data layer", "operationId": "getDataLayer", "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "schools", "aviation-facilities", "religious-organizations", "violence", "exempt-organizations" ] } }, { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "radius_km", "in": "query", "schema": { "type": "number", "minimum": 0.1, "maximum": 80, "default": 25 } }, { "name": "limit", "in": "query", "description": "Maximum returned records. The aviation-facilities source is capped at 25 by its nearest-airport contract.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "state", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "zip", "in": "query", "schema": { "type": "string", "pattern": "^\\d{5}$" } }, { "name": "city", "in": "query", "schema": { "type": "string", "maxLength": 160 } }, { "name": "aviation_details", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Only affects the aviation-facilities layer; embeds runways and frequencies." } ], "responses": { "200": { "description": "Normalized layer envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/layers/{layer}.geojson": { "get": { "tags": [ "Layers" ], "summary": "Get bare MapLibre-ready GeoJSON for one CCA data layer", "operationId": "getDataLayerGeoJson", "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "schools", "aviation-facilities", "religious-organizations", "violence", "exempt-organizations" ] } }, { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "radius_km", "in": "query", "schema": { "type": "number", "minimum": 0.1, "maximum": 80, "default": 25 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "GeoJSON FeatureCollection", "content": { "application/geo+json": { "schema": { "type": "object", "required": [ "type", "features" ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/map-boundaries": { "get": { "tags": [ "Tiles" ], "summary": "List state and county reference-border tile contracts", "description": "Returns same-origin MapLibre tile templates for authoritative U.S. Census state and county borders. Tile requests are streamed from `cca-maps-api` exclusively through the MAPS service binding.", "operationId": "listMapBoundaries", "responses": { "200": { "description": "CCA Maps reference-boundary catalog and binding availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/map-boundaries/{layer}/{z}/{x}/{y}.pbf": { "get": { "tags": [ "Tiles" ], "summary": "Stream a state or county boundary vector tile from CCA Maps", "description": "A same-origin streaming proxy over the MAPS service binding. State tiles use the `states` source layer; county tiles use `counties` and begin at zoom 4 to prevent regional clutter.", "operationId": "getMapBoundaryTile", "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "states", "counties" ] } }, { "name": "z", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 14 } }, { "name": "x", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "y", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Mapbox Vector Tile", "content": { "application/x-protobuf": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "204": { "description": "The tile contains no boundary features." }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/related/{source}/{id}": { "get": { "tags": [ "Layers" ], "summary": "Get the full sibling-service record behind a data-layer result", "description": "Fetches the complete source record through its Cloudflare service binding and returns the canonical source-system URL. Use the identifiers carried on layer features: a CCA Schools MCI, an airport ident, a canonical CCA Religious Orgs congregation id, a violence incident UUID, or an exempt-organization EIN.", "operationId": "getRelatedRecord", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "schools", "aviation-facilities", "religious-organizations", "violence", "exempt-organizations" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CCA Schools MCI, airport ident, CCA Religious Orgs id, violence incident UUID, or exempt-organization EIN." }, { "name": "country", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "Optional airport identifier disambiguation for aviation-facilities." }, { "name": "authority", "in": "query", "schema": { "type": "string" }, "description": "Optional airport source-authority disambiguation for aviation-facilities." } ], "responses": { "200": { "description": "Full source record, canonical detail URL, and upstream meta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tract/{geoid}": { "get": { "tags": [ "Tracts" ], "summary": "Get the cached/refreshed multi-source bundle for one tract", "operationId": "getTract", "parameters": [ { "name": "geoid", "in": "path", "required": true, "description": "11-digit Census tract GEOID.", "schema": { "type": "string", "pattern": "^\\d{11}$" }, "example": "11001980000" }, { "name": "sources", "in": "query", "description": "Comma-separated source ids or slices. Accepted slices: acs, health, svi, environment, risk, food.", "schema": { "type": "string" }, "example": "acs,health,svi" }, { "name": "fields", "in": "query", "description": "Comma-separated top-level response fields to retain.", "schema": { "type": "string" }, "example": "tract_geoid,tract_name,acs_data,updated_at" }, { "name": "refresh", "in": "query", "description": "Bypass freshness checks for the selected sources. Refreshed responses are not cached at HTTP level.", "schema": { "type": "boolean", "default": false } }, { "name": "acs_year", "in": "query", "description": "The configured default vintage is cached; historical vintages are request-local.", "schema": { "$ref": "#/components/schemas/AcsYear" } }, { "name": "lat", "in": "query", "description": "Optional latitude used with lon for the USDA 2010-tract spatial fallback.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "description": "Optional longitude used with lat for the USDA 2010-tract spatial fallback.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "Tract bundle", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TractBundle" } } } ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tract/{geoid}/{slice}": { "get": { "tags": [ "Tracts" ], "summary": "Get one source slice for a tract", "operationId": "getTractSlice", "description": "Only the requested source is eligible for refresh. `fields` applies to fields inside the slice payload.", "parameters": [ { "name": "geoid", "in": "path", "required": true, "description": "11-digit Census tract GEOID.", "schema": { "type": "string", "pattern": "^\\d{11}$" }, "example": "11001980000" }, { "name": "slice", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "acs", "health", "svi", "environment", "risk", "food" ] } }, { "name": "fields", "in": "query", "description": "Comma-separated top-level response fields to retain.", "schema": { "type": "string" }, "example": "tract_geoid,tract_name,acs_data,updated_at" }, { "name": "refresh", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "acs_year", "in": "query", "description": "The configured default vintage is cached; historical vintages are request-local.", "schema": { "$ref": "#/components/schemas/AcsYear" } }, { "name": "lat", "in": "query", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "Single source slice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tract/{geoid}/sources": { "get": { "tags": [ "Tracts" ], "summary": "Inspect availability and freshness for every tract source", "operationId": "getTractSources", "description": "D1-only metadata read; does not refresh the tract.", "parameters": [ { "name": "geoid", "in": "path", "required": true, "description": "11-digit Census tract GEOID.", "schema": { "type": "string", "pattern": "^\\d{11}$" }, "example": "11001980000" } ], "responses": { "200": { "description": "Per-source freshness", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "tract_geoid", "sources" ], "properties": { "tract_geoid": { "type": "string", "pattern": "^\\d{11}$" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceFreshness" } } } } } } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tract/{geoid}/sources/{source}": { "get": { "tags": [ "Tracts" ], "summary": "Inspect one source freshness record for a tract", "operationId": "getTractSource", "parameters": [ { "name": "geoid", "in": "path", "required": true, "description": "11-digit Census tract GEOID.", "schema": { "type": "string", "pattern": "^\\d{11}$" }, "example": "11001980000" }, { "name": "source", "in": "path", "required": true, "description": "Canonical source id or short slice name.", "schema": { "type": "string" }, "examples": { "slice": { "value": "health" }, "canonical": { "value": "cdc-places" } } } ], "responses": { "200": { "description": "Source freshness", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "tract_geoid", "sources" ], "properties": { "tract_geoid": { "type": "string", "pattern": "^\\d{11}$" }, "sources": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/SourceFreshness" } } } } } } ] } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tiles": { "get": { "tags": [ "Tiles" ], "summary": "List Census boundary layers and ingestion availability", "operationId": "listTileLayers", "responses": { "200": { "description": "Tile layer catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tiles/{layer}.json": { "get": { "tags": [ "Tiles" ], "summary": "Get TileJSON 3.0 for one boundary layer", "operationId": "getTileJson", "parameters": [ { "$ref": "#/components/parameters/TileLayer" } ], "responses": { "200": { "description": "TileJSON", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/tiles/{layer}/{z}/{x}/{y}.pbf": { "get": { "tags": [ "Tiles" ], "summary": "Get a Mapbox Vector Tile from an R2 PMTiles archive", "operationId": "getVectorTile", "parameters": [ { "$ref": "#/components/parameters/TileLayer" }, { "name": "z", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 14 } }, { "name": "x", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "y", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Mapbox Vector Tile", "content": { "application/vnd.mapbox-vector-tile": { "schema": { "type": "string", "format": "binary" } } } }, "204": { "description": "The tile is valid but empty or outside the archive zoom range" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/tract/{geoid}/refresh": { "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Force-refresh every source for one tract", "description": "Also purges the tract:{geoid} Workers Cache tag when the public edge cache is enabled; data.public_cache reports the purge outcome without failing the refresh.", "operationId": "adminRefreshTract", "parameters": [ { "name": "geoid", "in": "path", "required": true, "description": "11-digit Census tract GEOID.", "schema": { "type": "string", "pattern": "^\\d{11}$" }, "example": "11001980000" }, { "name": "lat", "in": "query", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "Refreshed tract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/cache/purge": { "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Delete one tract from the KV mirror and the public edge cache", "operationId": "adminPurgeTractCache", "parameters": [ { "name": "geoid", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{11}$" } } ], "responses": { "200": { "description": "KV key purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/public-cache/purge": { "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Purge public Workers Cache entries", "description": "Purges responses cached by the PublicApiCache entrypoint. Provide tags, tracts, and/or path_prefixes, or everything:true alone. Tags are community, community:{class}, route:{route}, tract:{geoid}, tiles:{layer}, boundaries:{layer}, or related:{source}; at most 100 tags and prefixes per call. Workers Cache purges share a 5-per-minute account limit, so a rejected purge is reported in data.public_cache rather than retried.", "operationId": "adminPurgePublicCache", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "tags": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "tracts": { "type": "array", "maxItems": 100, "items": { "type": "string", "pattern": "^\\d{11}$" } }, "path_prefixes": { "type": "array", "maxItems": 100, "items": { "type": "string", "pattern": "^/" } }, "everything": { "type": "boolean" } } }, "example": { "tracts": [ "11001980000" ], "tags": [ "tiles:tracts" ] } } } }, "responses": { "200": { "description": "Purge requested; data.public_cache.status is purged, failed, or skipped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/ledger": { "get": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "List the 200 most recent ingest ledger records", "operationId": "adminGetLedger", "responses": { "200": { "description": "Dataset ledger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/status": { "get": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Admin-authenticated alias for service status", "operationId": "adminGetStatus", "responses": { "200": { "description": "Service status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/broadband/sync": { "post": { "tags": [ "Admin", "Broadband" ], "security": [ { "AdminKey": [] } ], "summary": "Start or return the active FCC BDC mirror Workflow", "operationId": "adminStartBroadbandSync", "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "all", "availability", "challenge", "funding" ], "default": "all" } }, { "name": "as_of_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "FCC BDC Workflow run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/broadband/status": { "get": { "tags": [ "Admin", "Broadband" ], "security": [ { "AdminKey": [] } ], "summary": "Get FCC BDC sync runs, mirror states, and recent failures", "operationId": "adminGetBroadbandStatus", "responses": { "200": { "description": "FCC BDC mirror status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/tiles/{layer}/put": { "put": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Stream a complete PMTiles archive into R2", "operationId": "adminPutTileArchive", "parameters": [ { "$ref": "#/components/parameters/TileLayer" } ], "requestBody": { "required": true, "content": { "application/vnd.pmtiles": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Archive stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } }, "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "POST alias for complete PMTiles upload", "operationId": "adminPostTileArchive", "parameters": [ { "$ref": "#/components/parameters/TileLayer" } ], "requestBody": { "required": true, "content": { "application/vnd.pmtiles": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Archive stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/tiles/{layer}/mpu": { "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Create an R2 multipart tile upload", "operationId": "adminCreateTileMultipartUpload", "parameters": [ { "$ref": "#/components/parameters/TileLayer" } ], "responses": { "200": { "description": "Multipart upload id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/tiles/{layer}/mpu/{uploadId}/parts/{partNumber}": { "put": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Stream one multipart upload part", "operationId": "adminUploadTilePart", "parameters": [ { "$ref": "#/components/parameters/TileLayer" }, { "$ref": "#/components/parameters/UploadId" }, { "name": "partNumber", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Uploaded part metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/tiles/{layer}/mpu/{uploadId}/complete": { "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Complete an R2 multipart tile upload", "operationId": "adminCompleteTileMultipartUpload", "parameters": [ { "$ref": "#/components/parameters/TileLayer" }, { "$ref": "#/components/parameters/UploadId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "partNumber", "etag" ], "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "etag": { "type": "string", "minLength": 1 } } } } } } } } }, "responses": { "200": { "description": "Completed archive metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/admin/tiles/{layer}/mpu/{uploadId}/abort": { "post": { "tags": [ "Admin" ], "security": [ { "AdminKey": [] } ], "summary": "Abort an R2 multipart tile upload", "operationId": "adminAbortTileMultipartUpload", "parameters": [ { "$ref": "#/components/parameters/TileLayer" }, { "$ref": "#/components/parameters/UploadId" } ], "responses": { "200": { "description": "Upload aborted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid path, query, or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Invalid admin key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "405": { "description": "Method not allowed; inspect the Allow response header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "500": { "description": "Internal service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Every requested upstream source failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Required service binding is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } } }, "components": { "securitySchemes": { "AdminKey": { "type": "apiKey", "in": "header", "name": "X-Admin-Key", "description": "Secret installed with `wrangler secret put ADMIN_KEY`." } }, "parameters": { "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "TileLayer": { "name": "layer", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "tracts", "block_groups", "counties", "zcta", "places", "congressional", "state_senate", "state_house", "school_unified", "msa", "puma", "urban_areas", "states" ] } }, "UploadId": { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } }, "schemas": { "AcsYear": { "type": "string", "enum": [ "2023", "2022", "2021", "2020" ], "default": "2023" }, "Envelope": { "type": "object", "required": [ "request_status", "message", "data", "meta" ], "properties": { "request_status": { "type": "string", "enum": [ "success", "error" ] }, "message": { "type": "string" }, "error_code": { "type": "string" }, "data": {}, "details": { "description": "Structured validation or upstream failure context on selected errors." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "cache": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "hit", "miss", "stale", "refreshed", "bypass", "partial" ] }, "layer": { "type": "string", "enum": [ "none", "kv", "d1", "r2" ] } } }, "upstream": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "skipped", "degraded", "error" ] }, "attempted": { "type": "array", "items": { "type": "string" } }, "succeeded": { "type": "array", "items": { "type": "string" } }, "no_coverage": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object" } } } }, "cycle": { "type": [ "string", "null" ] }, "as_of": { "type": [ "string", "null" ], "format": "date-time" }, "response_time_ms": { "type": "number" }, "count": { "type": "integer" } } }, "Source": { "type": "object", "required": [ "id", "slice", "name", "authority", "cadence" ], "properties": { "id": { "type": "string", "example": "cdc-places" }, "slice": { "type": "string", "example": "health" }, "name": { "type": "string" }, "authority": { "type": "string" }, "description": { "type": "string" }, "cadence": { "type": "string" }, "stale_after_days": { "type": [ "integer", "null" ] }, "available_years": { "type": "array", "items": { "type": "string" } }, "upstream_url": { "type": "string", "format": "uri" } } }, "SourceFreshness": { "allOf": [ { "$ref": "#/components/schemas/Source" }, { "type": "object", "properties": { "available": { "type": "boolean" }, "attempted": { "type": "boolean" }, "year": { "type": [ "string", "null" ] }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "age_days": { "type": [ "number", "null" ] }, "stale": { "type": "boolean" } } } ] }, "Pagination": { "type": "object", "required": [ "page", "per_page", "total", "total_pages" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "CensusTractIntersection": { "type": "object", "required": [ "geoid", "name", "code", "relationship", "contains_centroid" ], "properties": { "geoid": { "type": "string", "pattern": "^\\d{11}$" }, "name": { "type": "string" }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "state_fips": { "type": "string", "pattern": "^\\d{2}$" }, "county_fips": { "type": "string", "pattern": "^\\d{3}$" }, "area_land": { "type": [ "number", "null" ] }, "area_water": { "type": [ "number", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "relationship": { "type": "string", "enum": [ "intersects_zcta", "intersects_locality", "contains_centroid" ] }, "contains_centroid": { "type": "boolean" } } }, "GeographyResolution": { "type": "object", "required": [ "query", "match", "hierarchy", "tract_geoid" ], "properties": { "query": { "type": "object" }, "match": { "type": "object" }, "hierarchy": { "type": "object" }, "tract_geoid": { "type": "string", "description": "Containing tract for a point, or the ZIP centroid tract for backward compatibility." }, "centroid_tract_geoid": { "type": [ "string", "null" ], "pattern": "^\\d{11}$" }, "selected_tract_geoid": { "type": [ "string", "null" ], "pattern": "^\\d{11}$" }, "tracts": { "type": "array", "items": { "$ref": "#/components/schemas/CensusTractIntersection" } }, "geography_scope": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "zcta", "locality" ] }, "zcta": { "type": "string", "pattern": "^\\d{5}$" }, "locality_type": { "type": "string", "enum": [ "place", "county-subdivision" ] }, "geoid": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "tract_relationship": { "type": "string", "enum": [ "intersects" ] }, "tract_count": { "type": "integer", "minimum": 0 }, "tract_coverage_complete": { "type": "boolean" } } }, "tract_selection": { "type": "object", "properties": { "required": { "type": "boolean" }, "selected_geoid": { "type": [ "string", "null" ], "pattern": "^\\d{11}$" }, "centroid_geoid": { "type": [ "string", "null" ], "pattern": "^\\d{11}$" }, "available_count": { "type": "integer", "minimum": 0 } } }, "selected_tract_context": { "type": [ "object", "null" ], "description": "Point-resolved hierarchy at the selected tract internal point. Present for a selected ZIP tract so centroid-only block and district fields are never mixed with the selected tract.", "properties": { "tract_geoid": { "type": "string", "pattern": "^\\d{11}$" }, "match": { "type": "object" }, "hierarchy": { "type": "object" }, "as_of": { "type": "string", "format": "date-time" } } }, "tract_data": { "oneOf": [ { "$ref": "#/components/schemas/TractBundle" }, { "type": "null" } ] }, "tract_aggregate": { "oneOf": [ { "$ref": "#/components/schemas/ZipTractAggregate" }, { "type": "null" } ] } } }, "ZipTractAggregate": { "type": "object", "required": [ "tract_geoids", "aggregate_meta" ], "properties": { "tract_geoid": { "type": "null" }, "tract_geoids": { "type": "array", "items": { "type": "string", "pattern": "^\\d{11}$" } }, "tract_name": { "type": "string" }, "acs_data": { "type": [ "object", "null" ] }, "places_data": { "type": [ "object", "null" ] }, "svi_data": { "type": [ "object", "null" ] }, "fema_nri_data": { "type": [ "object", "null" ] }, "usda_food_data": { "type": [ "object", "null" ] }, "ejscreen_data": { "type": [ "object", "null" ] }, "aggregate_meta": { "type": "object", "required": [ "scope", "geography_type", "geography_id", "geography_label", "requested_tract_count", "cached_tract_count", "complete", "coverage" ], "properties": { "scope": { "type": "string", "enum": [ "zcta-intersecting-tracts", "locality-intersecting-tracts" ] }, "zcta": { "type": [ "string", "null" ], "pattern": "^\\d{5}$" }, "geography_type": { "type": "string", "enum": [ "zcta", "locality" ] }, "geography_id": { "type": "string" }, "geography_label": { "type": "string" }, "requested_tract_count": { "type": "integer", "minimum": 0 }, "cached_tract_count": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean" }, "missing_tract_geoids": { "type": "array", "items": { "type": "string" } }, "incomplete_geoids": { "type": "array", "items": { "type": "string" } }, "population": { "type": [ "number", "null" ] }, "weight": { "type": "string" }, "methods": { "type": "object" }, "coverage": { "type": "object", "additionalProperties": { "type": "object" } }, "limitations": { "type": "string" }, "refresh": { "type": "object" } } } } }, "TractBundle": { "type": "object", "required": [ "tract_geoid", "state_fips", "county_fips", "tract_code" ], "properties": { "tract_geoid": { "type": "string", "pattern": "^\\d{11}$" }, "state_fips": { "type": "string", "pattern": "^\\d{2}$" }, "county_fips": { "type": "string", "pattern": "^\\d{3}$" }, "tract_code": { "type": "string", "pattern": "^\\d{6}$" }, "tract_name": { "type": [ "string", "null" ] }, "acs_data": { "type": [ "object", "null" ] }, "acs_year": { "type": [ "string", "null" ] }, "acs_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "places_data": { "type": [ "object", "null" ] }, "places_year": { "type": [ "string", "null" ] }, "places_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "svi_data": { "type": [ "object", "null" ] }, "svi_year": { "type": [ "string", "null" ] }, "svi_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "ejscreen_data": { "type": [ "object", "null" ] }, "ejscreen_year": { "type": [ "string", "null" ] }, "ejscreen_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "fema_nri_data": { "type": [ "object", "null" ] }, "fema_nri_year": { "type": [ "string", "null" ] }, "fema_nri_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "usda_food_data": { "type": [ "object", "null" ] }, "usda_food_year": { "type": [ "string", "null" ] }, "usda_food_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }