Skip to content

Add zip / zipcode analysis inputs to reports and data - #61

Merged
ejanalysis merged 6 commits into
mainfrom
codex/zip-analysis-662
Oct 15, 2026
Merged

ejanalysis merged 6 commits into
mainfrom
codex/zip-analysis-662

Conversation

@ejanalysis

@ejanalysis ejanalysis commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

ZIP codes cannot currently be passed directly to the API, despite EJAM v3.2022.3 supporting ejamit(zipcode=). Add zip and zipcode to GET/POST /report and POST /data, using ZCTA boundaries with a zero buffer by default. /report?zip=20912 requests a single-site report; /report?zipcode=20912,10605&sitenumber=0 requests the aggregate report.

Accept comma lists and JSON arrays; normalize leading zeroes/ZIP+4 and remove duplicates. Invalid/conflicting ZIP inputs return HTTP 400. Multi-ZIP report selection beyond the matched ZCTAs also returns 400 instead of silently falling back to a different ZIP; one-ZIP per-site URLs retain their original row labels. ZIP data rows include zipcode for the ZIP actually analyzed, preserving identity when postal ZIPs without ZCTAs are dropped. Geometry output uses the same codes and row order. FIPS remains separate: fips=10001 means Kent County, Delaware. Document first-download caching, missing ZCTAs, and examples.

Validation at de27a1c:

  • 114 ZIP route/helper/geometry/OpenAPI assertions passed locally with the real plumber router available; existing query pagination has 33 passing assertions. ZIP contract CI passes.
  • Real HTTP ZIP data passed for 20912, 10605, numeric 1001 -> 01001, and a missing ZCTA within a multi-ZIP geometry request. Alias/FIPS conflicts and an all-missing ZCTA request returned 400.
  • Single-site GET HTML/PDF, aggregate POST HTML/PDF, and selected-second-site GET HTML returned valid reports. Populations matched direct analysis (25,582 for 20912, 12,381 for 10605, 37,963 overall); PDF pages/maps and HTML layout were visually inspected.
  • R wrapper requests and actual ZIP analysis report links passed against the local HTTP API in the companion change.
  • The exact v3.2022.3 EJAM tag pinned by the API Dockerfile independently passed ZIP data, aggregate HTML, and single-site PDF checks.
  • Real zip=10001 data identifies New York (population 24,203), while fips=10001 with county scale identifies Delaware (population 182,400).

Implements Public-Environmental-Data-Partners/EJAM#662. Companion Public-Environmental-Data-Partners/EJAM#663 adds both aliases to R API wrappers, URL parsing and result report links, and copies this exact API controller. Merge the API PR first, refresh the companion mirror provenance to merged API main, then merge EJAM. Shiny ZIP entry and API handoff remain in EJAM#486; broader non-API helpers are tracked in EJAM#664. Hosted availability requires a separate deployment.

  • by Codex

@ejanalysis
ejanalysis marked this pull request as ready for review October 14, 2026 21:02
Updated the 'report' parameter description for clarity.

@ejanalysis ejanalysis left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The changes look good and pass tests, but we will try it out in the API run locally as well.

@ejanalysis
ejanalysis requested a lite review from Copilot October 15, 2026 00:52
@ejanalysis ejanalysis added the enhancement New feature or request label Oct 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

It changes core request-routing behavior for multiple API endpoints and depends on external EJAM/ZCTA behavior that can’t be fully validated here.

2 open findings
What changed in this PR

Adds first-class ZIP/ZCTA support to the EJAM-API analysis endpoints so callers can request /report and /data by zip/zipcode (aliases) in addition to existing location inputs, with normalization/validation and updated documentation/CI coverage.

Changes:

  • Add zip/zipcode parsing, normalization, and conflict validation, and wire ZIP inputs into EJAM analysis for GET/POST /report and POST /data.
  • Preserve analyzed ZIP identity in /data outputs (including after missing-ZCTA drops) and support ZIP geometries.
  • Add route-contract tests + a dedicated GitHub Actions workflow, and document ZIP/ZCTA usage in the README.
File Description
rest_controller.r Implements ZIP input normalization/validation and integrates ZIP routing into /report and /data, including ZIP identity preservation and geometry handling.
tests/​test-zip-api.R Adds contract-style tests for ZIP normalization, validation failures, route behavior, and OpenAPI param exposure (when deps are present).
README.md Documents new ZIP/ZCTA request patterns, normalization rules, and examples for /report and /data.
.github/​workflows/​test-zip-api.yaml Adds CI workflow to run the ZIP contract tests and existing query pagination assertions.

🧠 Review effort: Lite


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread .github/workflows/test-zip-api.yaml Resolved
Comment thread README.md Resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants