fix(parser): support nested field structures with backward compatibility #18
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
API changed response format from flat to nested structure for several fields:
- Census: census2010: {...} → census: {2010: {...}}
- ACS: acs-demographics: {...} → acs: {demographics: {...}}
- School districts: school: [...] → school_districts: {elementary: {...}}
Additionally, census field names changed (block → block_code, etc.) which
would break existing code accessing the old field names.
Changes:
- Add nested census parsing with dynamic year support (census2020-census2099+)
- Add nested ACS parsing supporting both simple and metric-specific formats
- Add nested school districts parsing (dict and list formats)
- Map new census field names to legacy names for backward compatibility
- Update ZIP4Data and FFIECData models with complete field definitions
- Remove hardcoded census year fields, use dynamic __getattr__ instead
Backward compatibility ensured:
- fields.census2020.block still works (maps to block_code)
- fields.census2020.blockgroup still works (maps to block_group)
- fields.census2020.tract still works (maps to tract_code)
Future-proof:
- census2031+ years work automatically without code changes
- cd120+ congressional districts work automatically
- Unknown API fields captured in extras dict
Fixes #15
Fixes #16
Closes #14
Closes #17
The test was checking for non-existent fields: - zip4.zip4 → zip4.plus4 - zip4.delivery_point → zip4.city_delivery Also added validation for zip9 and valid_delivery_area fields to match the actual API response structure. Verified with real API - test now passes.
MiniCodeMonkey
approved these changes
Nov 19, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fixes critical parsing issues where API response format changes from Geocodio broke field data parsing. The API migrated from flat to nested structures for census, ACS, and school district fields, and renamed several census field names, which would have caused breaking changes for existing users.
Changes
Nested Field Parsing
census: {2010: {...}, 2020: {...}}(nested) andcensus2010: {...}(flat) formatsacs: {demographics: {...}}(nested) andacs-demographics: {...}(flat) formatsschool_districts: {elementary: {...}}(nested dict) andschool: [...](flat list) formatsBackward Compatibility
block_code→blockblock_group→blockgrouptract_code→tractfields.census2020.blockcontinues to work without changesFuture-Proofing
__getattr__- supportscensus2031+automaticallycd120,cd121+work automatically without code changesfields.extrasModel Updates
ZIP4Datawith complete field definitions (record_type, carrier_route, plus4, zip9, etc.)FFIECDatawith comprehensive FFIEC CRA/HMDA fieldsSchoolDistrictwith new fields (lea_code, grade_low, grade_high)Test Plan
Unit Tests
Manual Testing with Real API
block,blockgroup,tract) correctly map to new valuesTest Coverage
Breaking Changes
None - This is a backward-compatible fix. Existing code continues to work without modifications.
Related Issues
Fixes #15 (Additional "Fields" not returning School District data)
Fixes #16 (PR to fix API Missing Responses)
Closes #14 (Fields not returning any additional data - nested census/ACS)
Closes #17 (School districts parsing issues)