Upgrading to Area API V4
Introduction
The new Area API V4 has been redesigned to accommodate the specific needs brought about by adopting a new set of geocodes to define geographical areas.
Because of the importance geocodes play in the Area API, we have made the decision to introduce a new version of each endpoint to make it clear that new geocodes are now being used. The original versions of the endpoints should work as originally designed, but new boundaries are only being geocoded using geoIdV4. Customers are encouraged to migrate to the new endpoints as soon as it is convenient to do so.
Endpoints Affected
The following endpoints have been enhanced to support the use of geoIdV4 in addition to geoid.
| Name | Original Endpoint | New Endpoint |
| Boundary | /areaapi/v2.0.0/boundary | /v4/area/boundary |
| CBSA Lookup | /areaapi/v2.0.0/cbsa/lookup | /v4/area/cbsa/lookup |
| County Lookup | /areaapi/v2.0.0/county/lookup | /v4/area/county/lookup |
| Geo ID Lookup | /areaapi/v2.0.0/geoid/lookup |
/v4/area/geoid/lookup |
| Hierarchy Lookup | /areaapi/v2.0.0/hierarchy/lookup | /v4/area/hierarchy/lookup |
| State | /areaapi/v2.0.0/state/lookup | /v4/area/state/lookup |
New Endpoints
Boundary
A new endpoint (/v4/area/boundary) has been added, providing customers with the definitions of geographic boundaries for a specific geography. This endpoint has been in beta and is now being made publicly available. It is being included
Geography Types
| CB | Census Block | CO | County |
| CS | County Subdivision | DB | School District |
| N1 | Macro Neighborhood (previously ND) |
N2 | Neighborhood (previously ND) |
| N3 | Sub-Neighborhood (previously ND) |
N4 | Residential Subdivision (previously RS) |
| PL |
Place |
PZ |
Zip Code |
| SB |
School | ST | State |
Example
GeoID Legacy Lookup
Provides a way to translate old geocodes into new geocodes. This endpoint has been added to aid with migration to handle unexpected situations in which an application has a value for geoid but doesn't have the new geocode (geoIdV4) to use with the new endpoints.
Example
The following example returns the new geocode (geoIdV4) for ST12 (Florida)
https://api.gateway.attomdata.com/areaapi/area/geoId/legacyLookup?geoId=ST12
{
"status": {
"version": "4",
"code": 0,
"msg": "SuccessWithResult",
"total": 1,
"transactionID": "f75d41dc7495b2e193891f41b3141c50"
},
"geoIdV4": [
{
"geo_id": "ST12",
"geoIdV4": "ff850e9d8ee56aca8737c96336afc8e2"
}
]
}
Location Lookup
Another endpoint added to assist with migrating applications. If you have the name associated with geography, this endpoint can be used to identify matching geographies and the geocodes applicable to each.
Example
The following example returns postal cities including "Las Vegas, NV" in their description
https://api.gateway.attomdata.com/v4/location/lookup?geographyTypeAbbreviation=CI&name=Las Vegas, NV
{
"status": {
"version": "4",
"code": 0,
"msg": "SuccessWithResult",
"total": 2,
"page": 1,
"pageSize": 10,
"transactionID": "86e0c172ced365988fcde8a97282ee9a"
},
"geographies": [
{
"geoIdV4": "d3711f6abd573a8f022d9d6b359b39d5",
"geographyName": "North las Vegas, NV",
"geographyTypeName": "Postal City",
"geographyTypeAbbreviation": "CI",
"details": {
"name": "North las Vegas",
"totalResidentCount": 75386,
"multiFamilyDeliveryUnitCount": 9819,
"singleFamilyDeliveryUnitCount": 65567,
"poBoxCount": 0,
"businessCount": 2709,
"areaSquareMiles": 72.8799612608461,
"longitude": -115.141092,
"latitude": 36.278659
}
},
{
"geoIdV4": "ec3137061e12cb66edc21c1225e457bf",
"geographyName": "Las Vegas, NV",
"geographyTypeName": "Postal City",
"geographyTypeAbbreviation": "CI",
"details": {
"name": "Las Vegas",
"totalResidentCount": 559332,
"multiFamilyDeliveryUnitCount": 156251,
"singleFamilyDeliveryUnitCount": 402690,
"poBoxCount": 391,
"businessCount": 32082,
"areaSquareMiles": 1659.5261988196498,
"longitude": -115.548831,
"latitude": 36.278887
}
}
]
}
Migration Process
Identify calls to the Area API
Identify any call made to the Area API V2
- /areaapi/v2.0.0/boundary
- /areaapi/v2.0.0/cbsa/lookup
- /areaapi/v2.0.0/county/lookup
- /areaapi/v2.0.0/geoid/lookup
- /areaapi/v2.0.0/hierarchy/lookup
- /areaapi/v2.0.0/state/lookup
Identify calls to other endpoints
Identify any other calls to ATTOM API that might be returning geocodes (geoid) used by the Area API calls
Change endpoint path
The endpoint paths should be changed to v4 (or higher).- /v4/area
Change logic for geocodes
Make all necessary changes to any logic associated with the use of geocodes.
- If geocodes originate from a previous API call, replace the use of geoid with geoIdV4 - See Geocodes
- If geocodes are coming from ATTOM data delivered as a bulk file, ensure you are now receiving the updated file format and adjust the process to include the new geoIdV4 from that source.
- If geocodes are coming from an outside source, a strategy should be developed to replace the old geocodes with the new geocodes. Two new endpoints have been added to assist with this process (Location Lookup and GeoId Lookup)