Python Library

Overview

The Aisle411 Python Library allows for users to call our web services by simply passing in a handful of arguments to functions, rather than making direct http web service calls using our RESTful web services. The task becomes even easier by the library allowing you to create an Aisle object that contains information that will be repeated in each web service call you make. By simply passing in parameters, lots of syntax mistakes can be avoided, as well as dodging the trouble of converting the json response into a more usable Python dict format.

Installation

Step One

To download a zip file of the Aisle411 Python Library, press the green [Download PyAisle] button!

Download PyAisle

Step Two

Start using the Aisle411 Python Library for all of your developer needs!

Aisle.py

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. Sample partner_id and partner secret values are provided here: 71 and 'Cyp<r7MZ=8]=a' respectively. You will receive a unique partner id and secret from us when you decide to move forward with integrating Aisle411 technology into your endeavor. The Sample Store provided has retailer_store_id = 1141489; this will be the store_id passed into the below functions.

Aisle Object Constructor
def __init__(self, host, partner_id, secret):
    self.hostname = "my company"
    self.part_id = 71
    self.secret = "Cyp<r7MZ=8]=a"

					    
#See? Easy! The following line shows an example of valid construction.
import Aisle as A

    aisle = A.Aisle(host_token, part_id, secret);
#   the host_token, part_id, and secret are defined in the config.py file.
#   You will want to fill these constants with the values provided to you by Aisle411, without them,
#   you will not be able to obtain data from the functions to follow.

Single Product Search


The Single Product Search function returns an array of products, which contain locations that satisfy the search term or UPC for a given store. There are different array structures based upon whether the match is exact, close, typo, or not found. There are examples located beneath the description.

Sample Request (Exact Match)
aisle = Aisle.Aisle(host_token, part_id, secret);
#function singleProductSearch(self, start, end, lat, long, term, store_id)					  
results = aisle.singleProductSearch(0, 1, 38.624691, -90.1847763, 'wheat bread', 1141489);

Single Product Search Parameters
self - The Aisle object
beg - The start of the search, usually 0
end - The limit of items to return in the search
lat - User latitude
long - User longitude
term - The search term or upc for the item
store_id - Retailer store id

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

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

Sample Request (Close Match)
aisle = Aisle.Aisle(host_token, part_id, secret);
#function singleProductSearch(self, start, end, lat, long, term, store_id)					  
print(tool.singleProductSearch(0, 10, 38.6256740, -90.1892740, "blueberry cream cheese", 1141489))

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

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

Sample Request (Typo)
aisle = Aisle.Aisle(host_token, part_id, secret);
#function singleProductSearch(self, start, end, lat, long, term, store_id)					  
print(tool.singleProductSearch(0, 10, 38.6256740, -90.1892740, "cokies", 1141489))

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

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

Sample Request (Not Found)
aisle = Aisle.Aisle(host_token, part_id, secret);
#function singleProductSearch(self, start, end, lat, long, term, store_id)					  
print(tool.singleProductSearch(0, 10, 38.6256740, -90.1892740, "hammmnnnn", 1141489))

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

{'products': []}

List of Stores By User Location


The List of Stores By User Location returns an Array of stores near the user, each of which has detailed information. Stores are sorted by ascending distance from the user.

aisle = Aisle.Aisle(host_token, part_id, secret);
#function storesByLocation(self, beg, end, lat, long, zipcd)
print(tool.storesByLocation(0, 1, 38.6256740, -90.1892740, 0))

List of Stores By User Location Parameters
self - The Aisle object
beg - The start of the search, usually 0
end - The limit of items to return in the search
lat - User latitude
long - User longitude
zipcd - User zip code, if 0, will use latitude and longitude location information. If it's not 0, will use zip code instead.

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.

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

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

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.

aisle = Aisle.Aisle(host_token, part_id, secret);
#function localProductSearch(self, lat, long, dist, max, term)
print(tool.localProductSearch(38.6256740, -90.1892740, 10000, 5, 'coffee'))

Local Product Search Parameters
self - The Aisle object
lat - User latitude
long - User longitude
dist - Max radius from coordinates to search
max - Maximum number of stores to return
term - A search term or upc for the item

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 Python dict:

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

Shopping List Search


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.

aisle = Aisle.Aisle(host_token, part_id, secret);
#function shoppingListSearch(self, lat, long, store_id, shop_list){
print(tool.shoppingListSearch(38.6256740, -90.1892740, 1141489, shop_list))

Shopping List Search Parameters
self - The Aisle object
lat - User latitude
long - User longitude
store_id - Retailer store id
shop_list - A shopping list Array (see below)

//You can build a shopping list like this, filling as many items as you have.
shop_list = dict()
shop_list['name'] = 'mylist'
shop_list['items'] = []
items = ['milk', 'apple', 'juice', 'cookies', 'tomatoes', 'beer', 'paper']
for item in items:
    shop_list['items'].append({'name': item}) #this name parameter can instead be upc for a upc code search.
//When finished, just pass in the dict as the final parameter of shoppingListSearch
print(tool.shoppingListSearch(38.6256740, -90.1892740, 1141489, shop_list))					   
?>
Note: Building a json shopping list is as simple as making a dict with keys: ['name', 'items'] and populating the items dict using append. The other parameters are optional. The key 'name' can be replaced with 'upc' for a upc search.

A Shopping List Search using the above parameters will return the following Python dict:
{'shopping_list_mapping_info':
	{'retailer_store_id': 1141489,
	'timestamp': '2017-08-19T11:33:18-05:00'},
	'items':
	[
		{'synonym_id': 84535,
		'sections': [
			{'section': 'dairy',
			'aisle': 'Dairy',
			'item_sub_location_id': 40157579,
			'item_location_id': '1075258',
			'map_location_id': '24397943'}],
		'synonym_nm': 'milk',
		'name': 'milk'},
		{'synonym_id': 259243,
		'sections': [
			{'section': 'Fruits',
			'aisle': 'Produce',
			'item_sub_location_id': 40157574,
			'item_location_id': '1075255',
			'map_location_id': '24397875'}],
		'synonym_nm': 'apples',
		'name': 'apple'},
		{'synonym_id': 9994,
			'sections': [
			{'section': 'apple juice',
			'aisle': '9',
			'item_sub_location_id': 40157542,
			'item_location_id': '1026277',
			'map_location_id': '24397912'}],
		'synonym_nm': 'juice',
		'name': 'juice'},
		{'synonym_id': 222727,
		'sections': [
			{'section': 'snacks',
			'aisle': '8',
			'item_sub_location_id': 40157553,
			'item_location_id': '1026276',
			'map_location_id': '24397916'}],
		'synonym_nm': 'cookies',
		'name': 'cookies'},
		{'synonym_id': 247511,
		'sections': [
			{'section': 'Vegetables',
			'aisle': 'Produce',
			'item_sub_location_id': 40157575,
			'item_location_id': '1075255',
			'map_location_id': '24397869'}],
		'synonym_nm': 'tomatoes',
		'name': 'tomatoes'},
		{'synonym_id': 20658,
		'sections': [
			{'section': 'beer',
			'aisle': '0',
			'item_sub_location_id': 40157571,
			'item_location_id': '1026268',
			'map_location_id': '24397940'}],
		'synonym_nm': 'beer',
		'name': 'beer'},
		{'synonym_id': 12600,
			'sections': [
			{'section': 'office supplies',
			'aisle': '10',
			'item_sub_location_id': 40157530,
			'item_location_id': '1026278',
			'map_location_id': '24397911'}],
		'synonym_nm': 'paper',
		'name': 'paper'}
	],
	'name': 'mylist'
}

Get Partner Store


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.

aisle = Aisle.Aisle(host_token, part_id, secret);
#function getPartnerStore(self, lat, long, store_id)
print(tool.getPartnerStore(38.6256740, -90.1892740, 1))

Get Partner Store Parameters
self - The Aisle object
lat - User latitude
long - User longitude
storeid - Vendor_store_nbr

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.

A Get Partner Store call using the above parameters will return the following Python dict:

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

Get Store Map


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.

aisle = Aisle.Aisle(host_token, part_id, secret);
#function getStoreMap(self, lat, long, store_id)
results = aisle.getStoreMap(38.624691, -90.1847763, 284);

Get Store Map Parameters
self - The Aisle object
lat - User latitude
long - User longitude
storeid - Retailer store id