@urbankitstudio/atlas 0.1.0 → 0.4.0

package/README.md

@@ -45,7 +45,20 @@ if (kane) {
 }
 ```
 
-### 3. Build a parcel-lookup deep-link
+### 3. Look up a county by FIPS code
+
+```ts
+import { findCountyByFips } from "@urbankitstudio/atlas";
+
+const kane = findCountyByFips("17089"); // 5-digit county FIPS (state + county)
+if (kane) {
+  console.log(kane.county, kane.stateSlug);
+  // → Kane illinois
+}
+// Unknown, malformed, or non-5-digit input returns undefined (never throws).
+```
+
+### 4. Build a parcel-lookup deep-link
 
 ```ts
 import { findCounty, buildParcelLookupDeepLink } from "@urbankitstudio/atlas";
@@ -62,6 +75,7 @@ const link = buildParcelLookupDeepLink(kane.endpoints[0]);
 | `listStates()` | `StateIndexEntry[]` — all 50 states + `populated` flag |
 | `findState(stateSlug)` | `StateFile \| undefined` |
 | `findCounty(stateSlug, countySlug)` | `CountyRecord \| undefined` |
+| `findCountyByFips(fips)` | `CountyRecord \| undefined` — match by 5-digit county FIPS |
 | `listCountiesByState(stateSlug)` | `CountyRecord[]` |
 | `buildParcelLookupDeepLink(endpoint)` | URL string into the UrbanKit lookup tool |
 | `slugify(s)`, `countySlugFromName(s)` | string helpers matching the atlas slug convention |
@@ -80,7 +94,7 @@ atlas.byStateSlug;      // Map<stateSlug, StateFile>
 
 ## Coverage today
 
-The atlas currently bundles 15 populated states (Arizona, California, Colorado, Florida, Georgia, Illinois, Minnesota, Nevada, New York, North Carolina, Ohio, Pennsylvania, Texas, Virginia, Washington) covering the largest counties in each. The remaining states are listed in the index with `populated: false`.
+The atlas currently bundles **128 counties across 39 populated states**, covering the largest counties in each. Call `listStates()` and filter on `populated` for the live set; the remaining states are listed in the index with `populated: false`.
 
 Counties are added as their public REST endpoints are verified. Package versions bump when data refreshes — pin to a minor range (`^0.x`) to receive new counties without breaking changes.
 

package/data/alabama.json

@@ -0,0 +1,57 @@
+{
+  "stateSlug": "alabama",
+  "stateName": "Alabama",
+  "stateAbbrev": "AL",
+  "lastUpdated": "2026-05-15",
+  "counties": [
+    {
+      "id": "al-jefferson",
+      "state": "AL",
+      "stateName": "Alabama",
+      "stateSlug": "alabama",
+      "county": "Jefferson",
+      "countySlug": "jefferson-county",
+      "countyFips": "01073",
+      "hasPublicRest": true,
+      "endpoints": [
+        {
+          "url": "https://jccgis.jccal.org/server/rest/services/Basemap/Parcels/MapServer/0",
+          "serviceType": "MapServer",
+          "layerIndex": 0,
+          "layerName": "Parcels",
+          "supportsQuery": true,
+          "corsEnabled": null,
+          "searchFields": [
+            { "name": "PARCELID", "label": "Parcel ID", "searchable": true },
+            { "name": "OWNERNAME", "label": "Owner Name", "searchable": true },
+            { "name": "PROP_MAIL", "label": "Property Mailing Address", "searchable": false },
+            { "name": "Street_Name", "label": "Street Name", "searchable": true },
+            { "name": "Bldg_Number", "label": "Building Number", "searchable": false },
+            { "name": "ADDR_PSPR", "label": "Address (Street Number+Prefix)", "searchable": false },
+            { "name": "APARTMENT", "label": "Apartment", "searchable": false },
+            { "name": "CITYMAIL", "label": "Mailing City", "searchable": false },
+            { "name": "ZIP_MAIL", "label": "Mailing ZIP", "searchable": false },
+            { "name": "STATE_Mail", "label": "Mailing State", "searchable": false },
+            { "name": "Legal_Desc", "label": "Legal Description", "searchable": false },
+            { "name": "Property_City", "label": "Property City", "searchable": false },
+            { "name": "ZONING_BOE", "label": "Zoning (Board of Equalization)", "searchable": false },
+            { "name": "ACRES_APR", "label": "Appraised Acres", "searchable": false },
+            { "name": "AssdValue", "label": "Assessed Value", "searchable": false }
+          ],
+          "sampleQuery": "https://jccgis.jccal.org/server/rest/services/Basemap/Parcels/MapServer/0/query?where=UPPER(OWNERNAME)+LIKE+UPPER('%25SMITH%25')&outFields=PARCELID,OWNERNAME,PROP_MAIL,Street_Name,Property_City&returnGeometry=false&f=json&resultRecordCount=10",
+          "license": "public",
+          "licenseUrl": "https://www.jccal.org/Default.asp?ID=1220&pg=Enterprise+GIS",
+          "status": "live",
+          "lastVerified": "2026-05-15",
+          "verifiedBy": "manual"
+        }
+      ],
+      "contact": {
+        "department": "Jefferson County Commission GIS / Information Technology Services — EGIS",
+        "url": "https://data-jeffco-al.opendata.arcgis.com/",
+        "email": null
+      },
+      "notes": "Jefferson County AL (Birmingham, pop. 670,000; FIPS 01073) Basemap/Parcels layer. Data maintained by Jefferson County Tax Assessor Office and updated nightly. 70+ fields confirmed including PARCELID, OWNERNAME, Name2, PROP_MAIL, CITYMAIL, ZIP_MAIL, STATE_Mail, Bldg_Number, Street_Name, Street_Type, Street_Dir, ADDR_APR, ZIP, Property_City/State, Legal_Desc, SUBDIV_NAME, ZONING_BOE, Water/Sewer/Gas, ACRES_APR, GIS_ACRES, PrevParcelLand/Imp/Total, AssdValue, TotalMHValue, Cls, TAX_CODE, DISTRICT, ESN_NUM, FIREDEPTNAME, NEIGHBOR_N, SchDist, MapNumber, Sqft. OWNERNAME field returns padded fixed-width strings (trim on use). Note: distinct from Jefferson County CO (FIPS 08059) and Jefferson County KY (Louisville; FIPS 21111) already in atlas. Verified 2026-05-15: SMITH returns Birmingham-area addresses."
+    }
+  ]
+}

package/data/alaska.json

@@ -0,0 +1,51 @@
+{
+  "stateSlug": "alaska",
+  "stateName": "Alaska",
+  "stateAbbrev": "AK",
+  "lastUpdated": "2026-05-15",
+  "counties": [
+    {
+      "id": "ak-anchorage",
+      "state": "AK",
+      "stateName": "Alaska",
+      "stateSlug": "alaska",
+      "county": "Anchorage",
+      "countySlug": "anchorage-municipality",
+      "countyFips": "02020",
+      "hasPublicRest": true,
+      "endpoints": [
+        {
+          "url": "https://services1.arcgis.com/7HDiw78fcUiM2BWn/arcgis/rest/services/AK_Parcels/FeatureServer/0",
+          "serviceType": "FeatureServer",
+          "layerIndex": 0,
+          "layerName": "AK_Parcels",
+          "supportsQuery": true,
+          "corsEnabled": null,
+          "searchFields": [
+            { "name": "parcel_id", "label": "Parcel ID", "searchable": true },
+            { "name": "owner", "label": "Owner Name", "searchable": true },
+            { "name": "alt_owner", "label": "Alternate Owner Name", "searchable": true },
+            { "name": "property_type", "label": "Property Type (Residential/Commercial/etc.)", "searchable": false },
+            { "name": "property_use", "label": "Property Use Description", "searchable": false },
+            { "name": "land_value", "label": "Land Value", "searchable": false },
+            { "name": "building_value", "label": "Building Value", "searchable": false },
+            { "name": "total_value", "label": "Total Assessed Value", "searchable": false },
+            { "name": "local_gov", "label": "Local Government (filter: Anchorage Municipality)", "searchable": true }
+          ],
+          "sampleQuery": "https://services1.arcgis.com/7HDiw78fcUiM2BWn/arcgis/rest/services/AK_Parcels/FeatureServer/0/query?where=UPPER(local_gov)+LIKE+'%25ANCHORAGE%25'+AND+UPPER(owner)+LIKE+UPPER('%25SMITH%25')&outFields=parcel_id,owner,alt_owner,property_type,land_value,total_value,local_gov&returnGeometry=false&f=json&resultRecordCount=10",
+          "license": "public",
+          "licenseUrl": "https://services1.arcgis.com/7HDiw78fcUiM2BWn/arcgis/rest/services/AK_Parcels/FeatureServer",
+          "status": "live",
+          "lastVerified": "2026-05-15",
+          "verifiedBy": "manual"
+        }
+      ],
+      "contact": {
+        "department": "Alaska Statewide Parcel Layer (combined from local government sources)",
+        "url": "https://services1.arcgis.com/7HDiw78fcUiM2BWn/arcgis/rest/services/AK_Parcels/FeatureServer",
+        "email": null
+      },
+      "notes": "15 fields confirmed: OBJECTID, parcel_id, owner, alt_owner, property_type, property_use, land_value, building_value, total_value, local_gov, datetime_processed, feature_id, Shape__Area, Shape__Length, GlobalID. This is the Alaska Statewide Parcel FeatureServer, combining parcel data from various local government bodies in Alaska. Filter by local_gov field — use UPPER(local_gov) LIKE '%ANCHORAGE%' for Anchorage Municipality parcels (confirmed returning real parcels including United Airlines, residential, etc.). Owner query confirmed working. NOTE: Alaska does not have counties — it has boroughs and a small number of unified municipalities. Anchorage is officially the Municipality of Anchorage (FIPS 02020). This statewide service also covers Fairbanks North Star Borough, Matanuska-Susitna Borough, and other AK jurisdictions via the local_gov field. Coverage and completeness vary by participating jurisdiction."
+    }
+  ]
+}

package/data/arizona.json

@@ -2,7 +2,7 @@
   "stateSlug": "arizona",
   "stateName": "Arizona",
   "stateAbbrev": "AZ",
-  "lastUpdated": "2026-05-11",
+  "lastUpdated": "2026-05-15",
   "counties": [
     {
       "id": "az-maricopa",
@@ -51,5 +51,98 @@
       },
       "notes": "57 fields confirmed including APN, APN_DASH, BOOK, MAP, ITEM, FLOOR, OWNER_NAME, MAIL_ADDR1/2, MAIL_CITY, MAIL_STATE, MAIL_ZIP, MAIL_CNTRY, PHYSICAL_ADDRESS, PHYSICAL_CITY, PHYSICAL_ZIP, PHYSICAL_STREET_NUM/DIR/NAME/TYPE, DEED_NUMBER, DEED_DATE, SALE_DATE, SALE_PRICE, MCRNUM, SUBNAME, LAND_SIZE, LOT_NUM, CONST_YEAR, LIVING_SPACE, INCAREOF, FCV_CUR/PREV, LPV_CUR/PREV, TAX_YR_CUR/PREV, CITY_ZONING, JURISDICTION, BLOCK, TRACT. Owner query tested and confirmed. The MaricopaDynamicQueryService layer 3 (Parcels) is the full-attribute layer backing the Parcel Viewer at maps.mcassessor.maricopa.gov. A separate 'Parcels' MapServer at gis.mcassessor.maricopa.gov/arcgis/rest/services/Parcels/MapServer also exists but has fewer fields. APN format: 8-digit with no dashes (e.g. '10101347'); APN_DASH adds dashes (e.g. '101-01-347')."
     }
+  ,
+    {
+      "id": "az-pima",
+      "state": "AZ",
+      "stateName": "Arizona",
+      "stateSlug": "arizona",
+      "county": "Pima",
+      "countySlug": "pima-county",
+      "countyFips": "04019",
+      "hasPublicRest": true,
+      "endpoints": [
+        {
+          "url": "https://mapdata.tucsonaz.gov/public/rest/services/PublicMaps/PropertyHousing/MapServer/17",
+          "serviceType": "MapServer",
+          "layerIndex": 17,
+          "layerName": "PAREGION",
+          "supportsQuery": true,
+          "corsEnabled": null,
+          "searchFields": [
+            { "name": "PARCEL", "label": "Parcel Number (Pima County APN)", "searchable": true },
+            { "name": "ADDRESSEE", "label": "Owner / Addressee Name", "searchable": true },
+            { "name": "SITE_ADDRESS", "label": "Site Address", "searchable": true },
+            { "name": "SITE_ZIPCITY", "label": "Site City", "searchable": false },
+            { "name": "TAXAREA", "label": "Tax Area Code", "searchable": false },
+            { "name": "FCV", "label": "Full Cash Value", "searchable": false },
+            { "name": "USE_DESC", "label": "Use Description", "searchable": false },
+            { "name": "TAXYR", "label": "Tax Year", "searchable": false },
+            { "name": "YearBuilt", "label": "Year Built", "searchable": false },
+            { "name": "MAIL1", "label": "Mailing Address Line 1", "searchable": true },
+            { "name": "MAIL2", "label": "Mailing Address Line 2", "searchable": true },
+            { "name": "legal_desc", "label": "Legal Description", "searchable": false }
+          ],
+          "sampleQuery": "https://mapdata.tucsonaz.gov/public/rest/services/PublicMaps/PropertyHousing/MapServer/17/query?where=UPPER(ADDRESSEE)%20LIKE%20UPPER('%25SMITH%25')&outFields=PARCEL,ADDRESSEE,SITE_ADDRESS,SITE_ZIPCITY,TAXYR,FCV,USE_DESC&returnGeometry=false&f=json&resultRecordCount=10",
+          "license": "public",
+          "licenseUrl": "https://mapdata.tucsonaz.gov/public/rest/services/PublicMaps/PropertyHousing/MapServer",
+          "status": "live",
+          "lastVerified": "2026-05-14",
+          "verifiedBy": "automated"
+        }
+      ],
+      "contact": {
+        "department": "City of Tucson / Pima County GIS — PropertyHousing MapServer (Pima Assessor PAREGION data)",
+        "url": "https://www.pima.gov/1796/Geographic-Information-Systems",
+        "email": null
+      },
+      "notes": "75 fields confirmed. The PAREGION layer (layer 17) is the county-wide Pima County Assessor parcel layer, hosted on the City of Tucson mapdata.tucsonaz.gov ArcGIS server, which aggregates both City of Tucson and unincorporated Pima County parcels. Layer 40 (PAREGION_TUCSON) is the Tucson-only subset; use layer 17 for full county coverage. Owner-name field is ADDRESSEE (holds the assessor's addressee/taxpayer name — equivalent to owner name for most records). PARCEL format is alphanumeric (e.g. '101013880'). Also exposes FCV (Full Cash Value), TAXYR, USE_DESC, MAIL1-5 (mailing address), LEGAL1-5 (legal description), SITE_ADDRESS, SITE_ZIPCITY, SITE_ZIP, TAXAREA, GISACRES, CURZONE_OL (zoning), and YearBuilt. The supportsQuery field reads null in layer metadata (ArcGIS 11.3 quirk), but the service capabilities string is 'Map,Query,Data' — queries work as confirmed by live testing. maxRecordCount=2000. The gisweb.pima.gov hostname NXDOMAINs; mapdata.tucsonaz.gov is the correct publicly accessible host."
+    },
+    {
+      "id": "az-pinal",
+      "state": "AZ",
+      "stateName": "Arizona",
+      "stateSlug": "arizona",
+      "county": "Pinal",
+      "countySlug": "pinal-county",
+      "countyFips": "04021",
+      "hasPublicRest": true,
+      "endpoints": [
+        {
+          "url": "https://rogue.casagrandeaz.gov/arcgis/rest/services/Pinal_County/Pinal_County_Parcels/MapServer/0",
+          "serviceType": "MapServer",
+          "layerIndex": 0,
+          "layerName": "Pinal County Parcels",
+          "supportsQuery": true,
+          "corsEnabled": null,
+          "searchFields": [
+            { "name": "PARCELID", "label": "Parcel ID (APN)", "searchable": true },
+            { "name": "LOWPARCELID", "label": "Lower Parcel ID", "searchable": true },
+            { "name": "OWNERNME1", "label": "Owner Name (Primary)", "searchable": true },
+            { "name": "OWNERNME2", "label": "Owner Name (Secondary)", "searchable": true },
+            { "name": "SITEADDRESS", "label": "Site Address", "searchable": true },
+            { "name": "CVTTXCD", "label": "Converted Tax Code", "searchable": false },
+            { "name": "CVTTXDSCRP", "label": "Tax Code Description", "searchable": false },
+            { "name": "USECD", "label": "Use Code", "searchable": false },
+            { "name": "USEDSCRP", "label": "Use Description", "searchable": false },
+            { "name": "CLASSCD", "label": "Class Code", "searchable": false },
+            { "name": "CLASSDSCRP", "label": "Class Description", "searchable": false },
+            { "name": "PRPRTYDSCRP", "label": "Property Description", "searchable": false }
+          ],
+          "sampleQuery": "https://rogue.casagrandeaz.gov/arcgis/rest/services/Pinal_County/Pinal_County_Parcels/MapServer/0/query?where=PARCELID+LIKE+'%25302%25'&outFields=PARCELID,SITEADDRESS,OWNERNME1,CLASSCD,CLASSDSCRP&returnGeometry=false&f=json&resultRecordCount=10",
+          "license": "public",
+          "licenseUrl": "https://www.pinal.gov/630/GIS",
+          "status": "live",
+          "lastVerified": "2026-05-15",
+          "verifiedBy": "manual"
+        }
+      ],
+      "contact": {
+        "department": "Pinal County GIS / Assessor's Office",
+        "url": "https://www.pinal.gov/630/GIS",
+        "email": null
+      },
+      "notes": "74 fields confirmed including OBJECTID, LOWPARCELID, PARCELID, BUILDING, UNIT, LGLSTARTDT, CVTTXCD, CVTTXDSCRP, SCHLTXCD, SCHLDSCRP, USECD, USEDSCRP, NGHBRHDCD, CLASSCD, CLASSDSCRP, SITEADDRESS, PRPRTYDSCRP, CNVYNAME, OWNERNME1, OWNERNME2. Owner name confirmed live: PARCELID LIKE '%302%' returns OWNERNME1='FELDMEIER BRIAN' in Arizona City AZ 85123. PARCELID format is typically 9-digit numeric string. Hosted on the City of Casa Grande ArcGIS server (rogue.casagrandeaz.gov) which serves Pinal County parcel data for the Phoenix metro south area (Chandler/Gilbert/Queen Creek/Maricopa City/Casa Grande). Capabilities: Query, Map, Data. maxRecordCount=1000. Note: the gismaps.pinalcountyaz.gov server is currently not externally accessible (HTTP 000); the Casa Grande mirror is the reliable public endpoint."
+    }
   ]
 }