Starting today, the ShopLocal team is proud to announce a much improved way of supporting our partners and retailers that use one or more of ShopLocal’s active APIs. Instead of sending members of our development community overwhelming 100+ pages of technical API documentation, the team will now be granting access to an online Wiki style site called the ShopLocal Developer Center.
If you are a current development partner or in the process of evaluating a ShopLocal API, please send an email to apisupport@shoplocal.com and someone from the team will get you setup with the required access.
The ShopLocal Developer Center promises always on access, an up-to-date and accurate set of technical API documentation for all the the various ShopLocal APIs that is rich with examples and easy to navigate and use.
The vision of the ShopLocal Developer Center is to hold a developer’s hand when first being introduced to a ShopLocal API so as to make it easier for them to develop their own unique applications with these powerful web services ShopLocal offers. With this goal in mind, the team has added some additional resources to the ShopLocal Developer Center that were never previously available which include:
- API Examples – sample iPhone and Banner ad application with more examples coming soon
- Frequently Asked Questions (FAQs) based on real world usage from ShopLocal’s own Client Services group
- Data Dictionary – to define ShopLocal nomenclature that is foreign to an external user, e.g. what a listing means, interest threshold exposure, etc.
The team also spent some serious time in revamping the technical documentation for the following APIs:
- SmartDelivery API (SDAPI)
- SmartBrand API (SBAPI)
- ShopLocal CrossRetailer API (SCRAPI)
- Local Offer Management System API (LOMSAPI)
Each API method for all of the APIs above now contains complete and standardized information including a:
- Short description of the API call (method) and how it can be used
- Required parameters
- Conditional parameters
- Optional parameters
- URL example to show the syntax of correctly constructed API call
- Data outputs (fields that are returned by call)
- Data output example (XML return examples)
A frequent question that the ShopLocal team is asked is one around the user – to – store assignment process. This involve determining where a user is currently located in the physical world and then calculating the closest retail store location to that user’s best known location.
Sounds easy hu? Well it really is not. This is one of the most core processes that literally every single customer that ShopLocal has every served content to has went through. ShopLocal does not have a national or “location-less” way of communicating. Every single system has one thing in common. Location as a required base input. So the word “Local” in our name (ShopLocal) is not just a cheap marketing tactic. It is a concept that is pervasive throughout the entire company. Everything that this company does is inherently “local”.
1. User location. The process always starts with putting a pin in the map so to speak where the user is located in the real world. This location is determined either by:
- A user entering a valid 5-Digit US ZIP code (ex. 60601)
- A user entering a valid City, State pair (ex. Chicago, IL)
- In this case, a conversion from a City, St to a ZIP code occurs in the background using US Postal data that assigns one single ZIP code (typically the most ‘downtown’ and central one) to every single city and town in America.
- GeoIP targeting information to derive a user’s best known location
- Although GeoIP targeting results in many detailed insights about location, the only one that is used in this process is ZIP code
- A marketer entering a valid Store ID number (see deep linking post)
So regardless of what method that is used to determine a user’s location, everything is normalized down to the ZIP code level within the ShopLocal system. From there the next step occurs. Finding the ZIP code centroid.
2. ZIP code centroids are defined by the US Census Bureau and they are a point near the center of the areas of a polygon for a 5-Digit ZIP Code. The centroid is calculated as the internal balance point, based on the coordinate extremes of the polygon. In cases where the polygon is irregular, the centroid may be adjusted so that ZIP Code labels never fall outside of the polygon. So for every single ZIP code, there is a matched ZIP Code centroid value that corresponds to a specific latitude / longitude pair of values. From here, the next steps occurs. Geo-coding the retailer’s store locations.
3. Geo-coding is the process of converting an address (ex. 225 N. Michigan Ave Chicago, IL 60601) into a latitude (lat) and longitude pair (lat) (ex. 41.886169, -87.624470). Most retailers send ShopLocal a complete list of all of their current open store locations. From this address, City, State, ZIP Code data ShopLocal converts each into a lat/long pair (or geocode). After this, the next step of distance calculation occurs.
4. Distance Calculation. At this point, we now have all the required inputs. One pair of lat/long values for the user and all of the associated lat/long values that correspond to the retailer’s stores. It’s time to start putting pins in the map. From the illustration below, one can quickly see how this plays out in reality. Using some farily simple math, one can exactly calculate the distance between the ZIP code centroid and each of the nearby store locations. The closest store location wins the prize of becoming the user’s local store.
Conclusions
This process works really well, but it is not perfect. One of the classic flaws is illustrated below where due to the fact that ZIP code centroid is how the system determines what is close by, there exists a risk and possibility that closer store may be ignored and routed around. However the reality is, asking users to enter a ZIP code is enough of a risky proposition (on average around 10% of users abandon when prompted to input their ZIP code or City,St pair) so asking for a full address is going to carry even worse abandonment rates. This method truly is the best available and is frequently used across the location based industry as an established best practice of determining store locations nearby to a user.
So by only using ZIP codes to determine what store is the closest, there are possibilities that exist where the correct, auto-determined closest store is in fact NOT the closest physical store. The only way to eliminate this issue is to have users enter their complete home address (street name and number) so that a more exact "pin" can be placed in the map, and therefore the not-so-exact ZIP Code centroid would no longer have to be used.
Loading ...
Comments: 1