RESTful Web Services

Overview

The purpose of this document is to provide a detailed technical description of the client-server communication protocol that will be used for communication between the client application and the web service.

Tools

aisle411 API

The aisle411 API powers indoor search capabilities in your app. aisle411 has created processes for the collection and organization of location specific product inventory data that make it easy to search. Strategic partners can integrate the aisle411 search API for free with the aisle411 Ad SDK, or can inquire about a licensing model.

aisle411 Maps SDK

The aisle411 Maps SDK delivers searchable, interactive indoor maps for your app.

aisle411 Ad SDK

Monetize your in-store mobile engagements by delivering context and location aware messaging. The aisle411 proprietary ad delivery engine targets shoppers based on actual in-aisle interaction within your app, driving incremental basket items and providing you with access to brand digital budgets.

Using the Web Services

Guidelines

In this document it is assumed that the URL for the service is https://qa.aisle411.ws/webservices3/.

Request parameters are passed as GET-request parameters. The response from the server should be in JSON format. In addition to the request parameters specific to the request, the partner key (‘partner_id’) should be sent in the parameter string.

There are several methods that accept additional parameters ‘start’ and ‘end’. These parameters limit the number of the objects returned by the method. If these parameters are omitted, the service must return a number of objects that is not greater than 100, starting with the first object in the list. This approach allows the application to:

  • Incrementally download the data from the server (for example, download the first 50 entries, then the next 50 entries, etc.)
  • Decrease the load on both the server and the application when the total number of objects is significant.

Authentication

Each method should accept an authentication token. Before the server completes the request it must verify that the token is valid. If the token is not valid, the server will return an error.
To create an authentication token you need a partner id and partner secret. To get these please contact tech@aisle411.com.

GET requests

For GET requests, the authentication token will be generated using the following method:

  • Request parameters are sorted alphabetically.
  • Method name, without .php, and the sorted request parameters including their names and ‘&’ delimiter (exception: the auth parameter is tagged at the end of the string) are concatenated into a single string. Escape sequences must be converted into appropriate characters before adding the value of parameter to the resulting string.
  • A secret_key is added to the resulting string after a ‘&’ delimiter (the same secret_key will be used on the client and server side to verify access to the data).
  • An MD5 hash value is calculated from the resulting string.

Below is an example for the method getstores:

https://qa.aisle411.ws/webservices3/getstores.php?latitude=12.2142245633& longitude=134.234266345&partner_id=71&start=0&end=2

Secret: (Cyp<r7MZ=8]=a
The Algorithm will work as follows:

  • All the parameters will be sorted in ascending order, and a concatenation of the parameters will be produced (method name will be added to the beginning of the string):
    getstores?end=2&latitude=12.2142245633&longitude=134.234266345&partner_id=71&start=0
  • The secret will be added to the end of string:
    getstores?end=2&latitude=12.2142245633&longitude=134.234266345&partner_id=71&start=0&(Cyp<r7MZ=8]=a
  • MD5 hash from the resulting string will be calculated:
    7c2552b2d05f526ab1302235a39b19b6
  • The resulting URL for the method will be:
    https://qa.aisle411.ws/webservices3/getstores.php?latitude=12.2142245633&longitude=134.234266345&partner_id=71&start=0&end=2&auth=7c2552b2d05f526ab1302235a39b19b6

In this document ‘auth’ and ‘partner_id’ parameter is omitted for all the methods. The ‘auth’ parameter will be added as the last parameter of the method.


Sample PHP Function to generate Hash String
function generateHash($function, $parameters) { 
$hashString = $function . "?";
    if (count($parameters) > 0) {
    ksort($parameters);
        foreach($parameters as $key => $value) {
            $hashString .= $key . "=" . $value . "&"; 
        }
    }
    // Add the secret word 
    $hashString .= "(Cyp<r7MZ=8]=a"; 
    return md5($hashString);
}

POST Requests

For the POST requests authentication token will be generated using the following algorithm.

  • Concatenation of the POST request body with the secret
  • MD5 hash from the resulting string will be calculated

Below is the example for the method signin:

https://qa.aisle411.ws/webservices3/locateitems.php
Body:
{"device_token":"device_token","latitude":38.6256740,"longitude":-90.1892740,"partner_id":71,"retailer_store_id":1141489,"shopping_list_data":{"name":"Sample","items":[{"name":"milk"},{"name":"ketchup"},{"name":"cookies"}]}}

Secret: (Cyp<r7MZ=8]=a
The Algorithm will work as follows:

  • A concatenation of the request body and the secret will be produced:
    {"device_token":"device_token","latitude":38.6256740,"longitude":-90.1892740,"partner_id":71,"retailer_store_id":1141489,"shopping_list_data":{"name":"Sample","items":[{"name":"milk"},{"name":"ketchup"},{"name":"cookies"}]}}(Cyp<r7MZ=8]=a
  • MD5 hash from the resulting string will be calculated:
    67918e7132bcc8ec115103a006857022

The calculated hash will be added to the HTTP message header as the following key/value pair:

Authentication: 67918e7132bcc8ec115103a006857022

The server will parse the ‘Authentication’ value from the HTTP header.

Sample PHP Function to generate Hash String

function generateHashForPost($parameterString) { 
    $parameterString = $parameterString .= "(Cyp<r7MZ=8]=a"; 
    return md5($parameterString);
}

Web Service Methods

The Aisle.py library makes your life as a Python developer very simple! To begin using the library in your code, you will want too create an Aisle object. As you will see in the snippet below, the constructor function for an Aisle object is very straightforward. Make sure that you edit the values in the provided config.py file to match the values provided to you by Aisle411. Without them, you will not be able to obtain data from the functions below, as your partner id and partner secret will not be validated.

Single Product Search


This will use the aisle411 web service url http://qa.aisle411.ws/webservices3/getstores.php
Sample Request (Exact Match)
https://qa.aisle411.ws/webservices3/searchproduct.php?end=10&latitude=38.625674&longitude=-90.189274&partner_id=71&retailer_store_id=1141489&start=0&term=wheat%20bread&auth=f97e37a5e8682ee8c39d1e08041b898a
Input Parameters
  • User location latitude('latitude')(optional)
  • User location longitude('longitude')(optional)
  • Address('location')(optional)
  • Devicetoken('device_token')
  • 'start'
  • 'end'

A single product search using the above parameters will return the following array:

{
	"products": [
		{
			"synonym_id": 66344,
			"synonym_nm": "wheat bread",
			"name": "wheat bread",
			"sections": [
				{
					"item_location_id": 1026269,
					"map_location_id": 24397938,
					"item_sub_location_id": 40157569,
					"aisle": "1",
					"section": "bread"
				}
			]
		}
	]
}

Sample Request (Close Match)
https://qa.aisle411.ws/webservices3/searchproduct.php?end=10&latitude=38.625674&longitude=-90.189274&partner_id=71&retailer_store_id=1141489&start=0&term=blueberry%20cream%20cheese&auth=371812c9e8e507c8abedef86359e808c

A Single Product Search using the above parameters will return the following array:

{
	"product_suggestions": [
		{
			"synonym_id": 6798,
			"synonym_nm": "cream cheese",
			"name": "blueberry cream cheese",
			"sections": [
				{
					"item_location_id": 1075258,
					"map_location_id": 24397943,
					"item_sub_location_id": 40157579,
					"aisle": "Dairy",
					"section": "dairy"
				}
			]
		}
	]
}

Sample Request (Typo)
https://qa.aisle411.ws/webservices3/searchproduct.php?end=10&latitude=38.625674&longitude=-90.189274&partner_id=71&retailer_store_id=1141489&start=0&term=cokies&auth=8f3e95a0b45413eec44c0dbaa48c5fd6

A Single Product Search using the above parameters will return the following array:

{
	"name": "cokies",
	"typo_suggestions": [
		"kicks",
		"coax",
		"cooks",
		"cookies",
		"kix"
	]
}

Sample Request (Not Found)
https://qa.aisle411.ws/webservices3/searchproduct.php?end=10&latitude=38.625674&longitude=-90.189274&partner_id=71&retailer_store_id=1141489&start=0&term=hammmmmnnn&auth=34fc51799e0b5780e9e9fd8e77372985

A Single Product Search using the above parameters will return the following Python dict:

{u'products': []}

List of Stores By User Location


This method returns the list of stores sorted by distance (to user). One of the following must be provided in the input parameters:

This will use the aisle411 web service url http://qa.aisle411.ws/webservices3/getstores.php
List of Stores By User Location Parameters
  • User location latitude('latitude')(optional)
  • User location longitude('longitude')(optional)
  • Address('location')(optional) - (This is a Zip Code)
  • Devicetoken('device_token')
  • 'start'
  • 'end'

Note: If latitude and longitude AND zip code are all provided, zip code will be used. Only when zip code is 0, will latitude and longitude be used. The response format for both coordinates and zip code are the same.

Sample Request with Zip Code
https://qa.aisle411.ws/webservices3/getstores.php?device_token=Haydens-MacBook-Pro.local&end=1&location=76133&partner_id=71&start=0&auth=271bdc5e853f937eb3552dad4336fc95
Sample Request with Coordinates
https://qa.aisle411.ws/webservices3/getstores.php?device_token=Haydens-MacBook-Pro.local&end=1&latitude=38.625674&longitude=-90.189274&partner_id=71&start=0&auth=717a46ac8818a9e9ed1c413f83528927
A stores by location search using either of the above parameters will return the following array:
{
	"stores": [
		{
			"retailer_store_id": 1141489,
			"aisle411_store_nbr": "00000",
			"retailer_store_nm": "Sample Grocery Store",
			"vendor_store_nbr": 1,
			"pla_enabled_flg": true,
			"store_viewable_flg": "Y",
			"store_tobe_removed_flg": "N",
			"phone_nbr": "555-555-5555",
			"store_map_url": "http:\/\/aisle411.ws\/store_maps\/1141489.imap",
			"street_address_txt": "1 Main St",
			"city_nm": "Fort Worth",
			"state_cd": "TX",
			"state_nm": "Texas",
			"zip_cd": 76133,
			"latitude": "32.658623",
			"longitude": "-97.418124",
			"store_logo_url": "http:\/\/aisle411.com\/retailer_logos\/Default_r.png",
			"store_website_url": "",
			"hours": "24\/7",
			"retailer_id": 1141488,
			"retailer_nm": "Sample Stores For Developers",
			"distance": 578.1421668504,
			"retailer_store_categories": [
			],
			"map": true
		},
	]
}

Local Product Search


The Local Product Search function returns an array of stores that carry the product, or product category, along with each store's details.

This will use the aisle411 web service url https://qa.aisle411.ws/webservices3/getstoreswithproduct.php
Local Product Search Parameters
  • Search term (‘term’) or UPC(‘upc’)
  • User location latitude(‘latitude’)
  • User location longitude(‘longitude’)
  • Distance from user’s location (‘distance’)
  • Desired Max Number Stores returned (‘max_stores’)
  • Device token(‘device_token’)
  • Your Partner Username (‘partner_id’)
Request Sample
https://qa.aisle411.ws/webservices3/getstoreswithproduct.php?device_token=Haydens-MacBook-Pro.local&distance=10000&latitude=38.625674&longitude=-90.189274&max_stores=5&partner_id=71&term=coffee&auth=0a03d922c814f179f14ec6e9236e1f7b

Note: The response format for both term and upc are the same.

A stores by location search using the above parameters will return the following array:

{
	"stores": [
		{
			"retailer_store_id": 1141489,
			"aisle411_store_nbr": "00000",
			"retailer_store_nm": "Sample Stores",
			"vendor_store_nbr": 1,
			"pla_enabled_flg": true,
			"store_viewable_flg": "Y",
			"store_tobe_removed_flg": "N",
			"phone_nbr": "555-555-5555",
			"store_map_url": "http:\/\/aisle411.ws\/store_maps\/1141489.imap",
			"street_address_txt": "1 Main St",
			"city_nm": "Fort Worth",
			"state_cd": "TX",
			"state_nm": "Texas",
			"zip_cd": 76133,
			"latitude": "32.658623",
			"longitude": "-97.418124",
			"store_logo_url": "http:\/\/aisle411.com\/retailer_logos\/Default_r.png",
			"store_website_url": "",
			"hours": "24\/7",
			"retailer_id": 1141488,
			"retailer_nm": "Sample Stores",
			"distance": 578.1421668504,
			"category_nm": "Stores",
			"location": "1",
			"sublocation": "Coffee",
			"map_location": 24397937,
			"retailer_store_categories": [
			],
			"map": true
		}
	]
}

Shopping List Search


Request Sample:

This will use the aisle411 web service url: https://qa.aisle411.ws/webservices3/locateitems.php

Post Body Request Sample:

{
   "device_token":"some_token",
   "retailer_store_id":12,
   "latitude":12.2142245633,
   "longitude":134.234266345,
   "shopping_list_data":"shopping list data in json format"
}

The Shopping List Search function requests location info for all the items in a shopping list. Make sure to raw url encode the search term to translate the spaces into %20.

Shopping List Data Format
  • Name(‘name’)–shopping list name,entered by app user
  • Items(‘items’)–list of shopping list items
    • Name(‘name’) – name of the product
    • UPC (‘upc’) – 12 or 13 digit UPC Number. This will override the name field if both are present.
    • UPCS(‘upcs’) – array of 12 or 13 digit UPC numbers. This can be used instead of UPC. This is used when you have many UPCs that map to a single product. Some examples are frozen pizzas with different topping options or different sizes for t- shirts.
    • Category Name(‘category_name’) – aisle411 has the ability to leverage custom categories you define as part of your search. These categories are custom built to your data and you’ll need to work with aisle411 to define the categories. If you send a category name with the item name we’ll use the category name to locate the section that closes matches the category. We’ll also return the category back to you in the response. This only works with the item name. It doesn’t have any affect if you send the UPC or an array of UPCs.
    • Quantity (‘quantity’) – quantity of the product items. This number will just be returned to you. This is optional.
    • Brand (‘brand’) – This will be returned to you. This is optional.
Sample Shopping List
{
	"name": "mylist",
	"items": [
		{
			"name": "milk"
		},
		{
			"name": "apple"
		},
		{
			"name": "juice"
		},
		{
			"name": "cookies"
		},
		{
			"name": "tomatoes"
		},
		{
			"name": "beer"
		},
		{
			"name": "paper"
		}
	]
}

A Shopping List Search using the above parameters will return the following array:

{
	"name": "mylist",
	"shopping_list_mapping_info": {
		"retailer_store_id": 1141489,
		"timestamp": "2017-08-19T13:42:49-05:00"
	},
	"items": [
		{
			"synonym_id": 84535,
			"synonym_nm": "milk",
			"name": "milk",
			"sections": [
				{
					"item_location_id": "1075258",
					"map_location_id": "24397943",
					"item_sub_location_id": 40157579,
					"aisle": "Dairy",
					"section": "dairy"
				}
			]
		},
		{
			"synonym_id": 259243,
			"synonym_nm": "apples",
			"name": "apple",
			"sections": [
				{
					"item_location_id": "1075255",
					"map_location_id": "24397875",
					"item_sub_location_id": 40157574,
					"aisle": "Produce",
					"section": "Fruits"
				}
			]
		},
		{
			"synonym_id": 9994,
			"synonym_nm": "juice",
			"name": "juice",
			"sections": [
				{
					"item_location_id": "1026277",
					"map_location_id": "24397912",
					"item_sub_location_id": 40157542,
					"aisle": "9",
					"section": "apple juice"
				}
			]
		},
		{
			"synonym_id": 222727,
			"synonym_nm": "cookies",
			"name": "cookies",
			"sections": [
				{
					"item_location_id": "1026276",
					"map_location_id": "24397916",
					"item_sub_location_id": 40157553,
					"aisle": "8",
					"section": "snacks"
				}
			]
		},
		{
			"synonym_id": 247511,
			"synonym_nm": "tomatoes",
			"name": "tomatoes",
			"sections": [
				{
					"item_location_id": "1075255",
					"map_location_id": "24397869",
					"item_sub_location_id": 40157575,
					"aisle": "Produce",
					"section": "Vegetables"
				}
			]
		},
		{
			"synonym_id": 20658,
			"synonym_nm": "beer",
			"name": "beer",
			"sections": [
				{
					"item_location_id": "1026268",
					"map_location_id": "24397940",
					"item_sub_location_id": 40157571,
					"aisle": "0",
					"section": "beer"
				}
			]
		},
		{
			"synonym_id": 12600,
			"synonym_nm": "paper",
			"name": "paper",
			"sections": [
				{
					"item_location_id": "1026278",
					"map_location_id": "24397911",
					"item_sub_location_id": 40157530,
					"aisle": "10",
					"section": "office supplies"
				}
			]
		}
	]
}

Get Partner Store


This will use the aisle411 web service url https://qa.aisle411.ws/webservices3/getpartnerstore.php

This method sends a request to the server with the store’s internal code and returns information about the corresponding store. If the store isn’t found in aisle411’s DB it returns a store array with null. This is used by retailers who want to translate their internal store numbers to Aisle411's globally unique ID for each store.

Get Partner Store Parameters
  • Internal Store Code(‘vendor_store_nbr’)
  • Device token(‘device_token’)
Output Parameters
  • 1. Store ID ('retailer_store_id')
  • 2. 'aisle411_store_nbr'
  • 3. Store name ('retailer_store_nm')
  • 4. Store categories('retailer_store_categories')(Disregardthis)
  • 5. Subscribed ('pla_enabled_flg') ('true' if the store is subscribed to the aisle411program, 'false' otherwise)
  • 6. Store phone number('phone_nbr')
  • 7. Address('street_address_txt')
  • 8. City('city_nm')
  • 9. State('state_nm')
  • 10. ZIP code ('zip_cd')
  • 11. Store latitude ('latitude')
  • 12. Store longitude ('longitude')
  • 13. Distance from user location in miles ('distance')
  • 14. Working hours of the store ('hours')
  • 15. Retailer id ('retailer_id')
  • 16. Retailer name ('retailer_nm')
  • 17. Store map flag ('map'). 'true' means that a store has a map, 'false' means that there is no map for this store.

Note: vendor_store_nbr is not the same as retailer_store_id. vendor_store_nbr is not unique, so you may need to do some filtering of your own.

https://aisle411.ws/webservices3/getpartnerstore.php?device_token=Haydens-MacBook-Pro.local&latitude=38.625674&longitude=-90.189274&partner_id=71&vendor_store_nbr=1&auth=1fcb334e3c20b6870677e6ac2cf3d5fe
A Get Partner Store call using the above parameters will return the following array:
{
	"stores": [
		{
			"retailer_store_id": 1141489,
			"aisle411_store_nbr": "00000",
			"retailer_store_nm": "Sample Grocery Store",
			"vendor_store_nbr": 1,
			"pla_enabled_flg": "Y",
			"store_viewable_flg": "Y",
			"store_tobe_removed_flg": "N",
			"phone_nbr": "555-555-5555",
			"store_map_url": "http:\/\/aisle411.ws\/store_maps\/1141489.imap",
			"street_address_txt": "1 Main St",
			"city_nm": "Fort Worth",
			"state_cd": "TX",
			"state_nm": "Texas",
			"zip_cd": 76133,
			"latitude": "32.658623",
			"longitude": "-97.418124",
			"store_logo_url": "",
			"store_website_url": "",
			"hours": "24\/7",
			"retailer_id": 1141488,
			"retailer_nm": "Sample Stores For Developers",
			"distance": 0
		}
	]
}

Get Store Map


This will use the aisle411 web service url https://aisle411.ws/webservices3/map.php

The Get Store Map function returns a file containing a map bundle, a .imap file. This map bundle is used with the Map SDK for your platform. To save time we recommend you cache the map locally on the device with the current timestamp. We send the Last-Modified-Date timestamp of the map to you through the Last-Modified header in the HTTP response header. You can use this to check if you should download the new map off the server, if the Last-Modified-Date is newer than the stored timestamp, or use the one you have cached.

Get Store Map Parameters
  • User location latitude(‘latitude’)
  • User location longitude(‘longitude’)
  • Store ID('retailer_store_id')

Request Sample:

https://qa.aisle411.ws/webservices3/map.php?latitude=38.625674&longitude=-90.189274&partner_id=71&retailer_store_id=1141489&auth=ec398610617b0223ace60309a1c6714b

Webmaps Overview

The Aisle411 Webmap services allow for users to interact with our mapping, location, and search services through HTTP calls to our various webmap functions. In this document you will learn how to use each of our webmap tools on a sample store. Once you obtain your own credentials, you will be able to access the same on additional stores based on your partner access.

Single Product Search


Single Product Search is a function that is used to locate a specific item by either search term or UPC in a specific store. The samples below will demonstrate displaying the map of the sample store along with pins for searches first by search term, and second by UPC.

The format for a single product search is as follows:

https://aisle411.ws/webservices3/webmaps/?partner_id={partner_id}&id={retailer_store_id&q={query}
Sample Search By Term
https://aisle411.ws/webservices3/webmaps/?partner_id=71&id=1141489&q=coffee
Sample Search By UPC
https://aisle411.ws/webservices3/webmaps/?partner_id=71&id=1141489&q=10087

You can see in the above that the distinction between search term and UPC isn't made by the user, but instead server-side, so you may input terms and UPCs interchangably without fear!

Shopping List Search


Shopping List Search is a function similar to Single Product Search, except it allows for multiple products to be searched at the same time. Also similar to the above, it accepts both items by search term and by UPC.

The format for a shopping list search is as follows:

http://aisle411.ws/webservices3/webmaps/?id=1141489&partner_id=71&q[]{query1}&q[]={query2}
Sample Search By Terms
http://aisle411.ws/webservices3/webmaps/?id=1141489&partner_id=71&q[]=cereal&q[]=bacon
Sample Search By Terms and UPC
http://aisle411.ws/webservices3/webmaps/?id=1141489&partner_id=71&q[]=cereal&q[]=10087

You can see in the examples above the Shopping List Search works well with both search terms and UPCs. You can add as many queries as you'd like by adding additional 'q[]={query}' to the end of the URL.