Upgrading to POI Endpoint V4

Introduction

The new POI API V4 represents a significant enhancement to the API. We have dramatically increased the amount of information available and much of the existing data has changed in various ways. As a result, we recommend everyone making use of the original POI API V2 look closely at the changes and decide how to take advantage of the changes being made for their own projects.

• We have moved to a new vendor who provides a significant number of improvements to the points of interest data provided. This is the same data that supports ATTOM Cloud.
  • The total number of fields available has increased from 18 to 59. This is consistent with the points of interest data already available in ATTOM Cloud.
  • Some of the existing fields have been retired, either because they are no longer available, no longer make sense, or had already been deprecated by the original source but never removed.
  • Almost all the fields have new names consistent with those used in ATTOM Cloud.
  • We have consolidated the category and lines of business searches into a single endpoint
• The geocoded used to identify a specific geographic area associated with a point of interest has changed to adopt the standardized geocoded employed across all other remaining ATTOM products. The new geocoded (geoIdV4) has been added to all endpoints that previously provided geocoded. Endpoints that support searching via a geocode will now accept the new geocodes.

Endpoints Affected

The following endpoints are impacted by this change. As part of V4, we have consolidated the POI API from five endpoints to two.

Data Enhancements

POI

• Points of interest are now geocoded to match with geographic areas such as census blocks, census block groups, and census tracts.
• Contact details for the business are provided
• Linkages added to populate social media such as Facebook and Yelp
• Additional industry classifications for each business
• More information to support the delivery of direct marketing material
• Addition of operating hours (where available)

Migration Process

The following outlines the series of steps necessary to upgrade applications from previous versions of POI API to POI API V4. It is important these changes be made as soon as possible as the older versions are being deprecated. It is likely that the older versions of POI API endpoints will stop working after June 30, 2023.

Note: There is no POI API V3. We adopted V4 across all ATTOM APIs, some of which had a V3.

1

Identify calls to POI API

Identify all the places in your code in which a call is made to any of the POI API V2 endpoints: -

• /poisearch/v2.0.0/business+category/lookup
• /poisearch/v2.0.0/lob/lookup
• /poisearch/v2.0.0/poi/geography
• /poisearch/v2.0.0/poi/point
• /poisearch/v2.0.0/poi/street+address

2

Identify calls to other endpoints

Identify any other calls to ATTOM API that might be generating geocoded (geoid) that are used in calls to the POI API.

3

Change endpoint path

The endpoint paths should be changed to v4 (or higher) and the endpoint name should be mapped to the new name

Original Endpoint	V4 Endpoint
/poisearch/v2.0.0/business+category/lookup	/v4/neighborhood/poi/categorylookup
/poisearch/v2.0.0/lob/lookup	/v4/neighborhood/poi/categorylookup
/poisearch/v2.0.0/poi/geography	/v4/neighborhood/poi
/poisearch/v2.0.0/poi/point	/v4/neighborhood/poi
/poisearch/v2.0.0/poi/street+address	/v4/neighborhood/poi

Refer to the documentation for the other APIs to get the new paths used for those endpoints.

4

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 geocoded. Two new endpoints have been added to assist with this process (Location Lookup and GeoId Legacy Lookup)

5

Make changes to business logic

With so many fields being added, we recommend looking closely at the business logic behind your projects to decide how you wish to leverage the enhancements made. It will be important to ensure you are processing the points of interest data that your project needs in a way that is consistent with how the data is now provided.

A separate spreadsheet is available to assist with making those changes.

POI-Migration-Kit.xlsx

The following is a summary of the options provided in the above spreadsheet for each field

Category	Action	Number of Fields
Name Change Only	Change logic to extract value from the endpoint using the new field name	8
Removed Field	No equivalent is available. Evaluate the option of removing data from display or calculations	3
New field	Decide if you wish to take advantage (at this time) of the many new fields added.	44