GeoGenius.Providers.SimpleMaps.Fips (geo_genius v0.2.0)

Copy Markdown View Source

The state a county FIPS code is assigned within.

A county FIPS is five digits: the two-digit FIPS of the state that assigns it, then a three-digit county code. 51107 is Loudoun County, and the 51 in front of it is Virginia. That prefix is the only statement of a county's state either SimpleMaps file makes that cannot disagree with itself -- a row's own state_id column describes the row, not the county, and the two differ wherever a mailing address crosses a state line. ZIP 20041 carries state_id DC and county_fips 51107: Dulles-area mail with a District of Columbia address, delivered to a county in Virginia. 150 of the source's 3,233 counties are named on rows of more than one state.

So the mapping has to run the other way -- from FIPS to state, not from the row -- and neither file carries it. uscities and uszips name states only by their two-letter postal code, never by state FIPS, and no row anywhere states that 51 is VA. Deriving the pair from the rows themselves is what the row-scoped provider callbacks cannot do: GeoGenius.Provider hands normalize/2 and asserted_relations/2 one staged row at a time with no accumulator between them, and the row that needs the answer -- the ZIP whose state and county disagree -- is exactly the row that gets it wrong. The table is therefore stated here.

It is US knowledge, and it lives in the provider because that is what a provider is: GeoGenius.Providers.SimpleMaps parses one vendor's two US files and nothing else. Nothing outside lib/geo_genius/providers/ knows a FIPS code from a postcode.

What is in the table

The fifty states, the District of Columbia, and the five inhabited territories the Census assigns a state-level FIPS to: American Samoa (60), Guam (66), the Northern Mariana Islands (69), Puerto Rico (72), and the US Virgin Islands (78). Every one of them appears in uszips as a state_id and has counties or county equivalents under it.

Three codes deliberately absent are the Freely Associated States -- FM, PW and MH -- which FIPS 5-2 once numbered 64, 70 and 68 before the standard was withdrawn. They are sovereign countries the USPS serves, they have no US counties, and no row of either file carries a county_fips under them. Listing withdrawn codes would invite a five-digit number that happens to start with 64 to be read as a county of Micronesia.

AA, AE and AP are absent for a stronger reason: they are USPS constructs for military mail, not places, and no FIPS numbers them at all. A county can never belong to one, which is precisely the assertion the row's own state column was making before the prefix was consulted.

Summary

Functions

Returns whether SimpleMaps' state code has a USPS identity but no Census state identity.

Returns the postal code of the state a five-digit county FIPS is assigned within, or nil when the code names no state this table carries.

Functions

non_census_state_code?(code)

@spec non_census_state_code?(term()) :: boolean()

Returns whether SimpleMaps' state code has a USPS identity but no Census state identity.

state_code(arg1)

@spec state_code(String.t()) :: String.t() | nil

Returns the postal code of the state a five-digit county FIPS is assigned within, or nil when the code names no state this table carries.

nil is the answer for anything that is not five characters long, and for a five-character code whose first two are not a state FIPS -- a truncated cell, a county equivalent from a numbering scheme this table does not describe, or a value the source simply got wrong. A caller that cannot name the state asserts nothing about it rather than falling back on the row's own state column, which is the value that is wrong in the case this exists for.