General Overview

This guide should help to get started using the Uberall Storefiner API. It is not meant as a detailed API documentation, but to convey the broader idea behind the design of the endpoints. The API Swagger documentation can be found here: <TBD>

Accessing the Uberall API

The Storefinder API must be accessed through this subdomain: https://locator.uberall.com/ - this assures caching of the response and provides minimum request time for the requester as well as stability for the Uberall application. The path for the storefinder endpoints is /api/storefinders, e.g. https://locator.uberall.com/api/storefinders/

Authentication

All requests against the API must be authenticated by the so called Storefinder Key. This key is public and will be used to identify which storefinder the request has been made from. The key must be present in the URL after the /api/storefinders part:  https://locator.uberall.com/api/storefinders/$key and is followed by the endpoint to invoke.

You can find the key if you have a Self-Service locator in the Html snippet under the data-key attribute:

If you have a different locator solution booked please consult with Uberall.

Basic Endpoints

There are four different basic endpoints powering the UB locator API that will be explained in the next part of this article

• /locations/all - to list all locations
• /locations - to search for specific locations
• /locations/$id - to get details about a specific location
• /filters - to get a list of unique values to filter by

Versioning

Versioning must be present on any request. An API Version is a date and needs to be added to the request as a param called v, e.g. https://locator.uberall.com/api/storefinders/$key/locations/all?v=20241126

Fieldmasks

All endpoints retrieving location data support a param called fieldMask (notice the spelling, it is case sensitive). It indicates which fields should be returned. If no fieldMask is present, a default one will be used. It is highly recommended to specify the fields required by the application. By reducing the amount of data that is returned by the API everyone benefits: the customer benefits from faster downloads, processing and display of the relevant information and the API can work with less data and as such putting less pressure on the system.

Every endpoint supports different fields in the fieldmask. The more results an endpoint could possibly return, the less fields are supported. This is to make the result sets smaller and manageable by the clients.

Basic Endpoints

List all locations

This endpoint is called in the beginning of a locator session to load a small subset of data for each and every location present in the locator. This data can include the ID, name, lat and lon so we can put the pin on the map or render the sitemap.

Sample request:

Possible fieldmask fields:

Search for locations/get more detail for multiple locations

This is a very versatile endpoint serving different purposes:

Geosearch

Sample request:

Filter

Sample request:

Load more information by IDs

Sample request:

Possible fieldmask fields:

Get details about a specific location

This endpoint is used to load all the data that could possibly be displayed on a local page.

Sample request:

Possible fieldmask fields:

Get unique values to filter by

In order to display a filter UI, e.g. the list of services or brands offered in all of the locations, this endpoint can be called and will return all the unique values for the given filters.

Currently supported filters:

• services
• brands
• custom filters added by the customer

Sample request: