Upgrading to Area API V4


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
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


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)
Zip Code
School ST State


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.


The following example returns the new geocode (geoIdV4) for ST12 (Florida)

    "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.


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)
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.