PHP Library

Overview

The Aisle411 PHP 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 PHP Array format.

Installation

Step One

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

Download AislePHP

Step Two

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

Aisle.php

The Aisle.php library makes your life as a PHP 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
<?php 
function __construct($host, $part_id, $secret) {
	$this->hostname = $host;
	$this->part_id = $part_id;
	$this->secret = $secret;
    }
//See? Easy! The following line shows an example of valid construction.
    $aisle = new Aisle("my company name", 71, "(Cyp<r7MZ=8]=a");
    /*  the host_token is a string that identifies the operator of the webservices calls,
    the part_id should be the number given to you by Aisle411, 71 is a sample used for this site,
    and the secret parameter given here is "(Cyp<r7MZ=8]=a".
    You will want to replace these parameters with the values provided to you by Aisle411,
    when you receive them to get greater access to our webservices. */  
?>

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)
<?php
//function singleProductSearch($beg, $end, $lat, $long, $term, $store_id)					  
print_r($tool->singleProductSearch(0, 10, 38.6256740, -90.1892740, "wheat bread", 1141489));
?>

Single Product Search Parameters
$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 for the item
$store_id - Retailer store id

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

Array
(
    [products] => Array
        (
            [0] => Array
                (
                    [synonym_id] => 66344
                    [synonym_nm] => wheat bread
                    [name] => wheat bread
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1026269
                                    [map_location_id] => 24397938
                                    [item_sub_location_id] => 40157569
                                    [aisle] => 1
                                    [section] => bread
                                )

                        )

                )

        )

)

Sample Request (Close Match)
<?php
//function singleProductSearch($beg, $end, $lat, $long, $term, $store_id)					  
$results = $aisle->singleProductSearch(0, 1, 38.624691, -90.1847763, 'blueberry cream cheese', 1141489);
?>

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

Array
(
    [product_suggestions] => Array
        (
            [0] => Array
                (
                    [synonym_id] => 6798
                    [synonym_nm] => cream cheese
                    [name] => blueberry cream cheese
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1075258
                                    [map_location_id] => 24397943
                                    [item_sub_location_id] => 40157579
                                    [aisle] => Dairy
                                    [section] => dairy
                                )

                        )

                )

        )

)

Sample Request (Typo)
<?php
$aisle = new Aisle(host_token, 71, "(Cyp<r7MZ=8]=a");
//function singleProductSearch($beg, $end, $lat, $long, $term, $store_id)					  
$results = $aisle->singleProductSearch(0, 1, 38.624691, -90.1847763, 'cokies', 1141489);
 ?>

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

Array
(
    [name] => cokies
    [typo_suggestions] => Array
        (
            [0] => kicks
            [1] => coax
            [2] => cooks
            [3] => cookies
            [4] => kix
        )

)

Sample Request (Not Found)
<?php
$aisle = new Aisle(host_token, 71, "(Cyp<r7MZ=8]=a");
//function singleProductSearch($beg, $end, $lat, $long, $term, $store_id)					  
print_r($tool->singleProductSearch(0, 10, 38.6256740, -90.1892740, "hammmmmnnn", 1141489));
?>

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

Array
(
    [products] => Array
        (
        )
)

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.

<?php
//function storesByLocation($beg, $end, $lat, $long, $zipcd)
print_r($tool->storesByLocation(0, 1, 38.6256740, -90.1892740, 0));
?>

List of Stores By User Location Parameters
$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 PHP Array:

Array
(
    [0] => Array
        (
            [retailer_store_id] => 1141489
            [aisle411_store_nbr] => 00000
            [retailer_store_nm] => Sample Grocery Store
            [vendor_store_nbr] => 1
            [pla_enabled_flg] => 1
            [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] => Array
                (
                )

            [map] => 1
        )

)

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.

<?php
//function localProductSearch($lat, $long, $dist, $max, $term)
print_r($tool->localProductSearch(38.6256740, -90.1892740, 10000, 5, 'coffee'));
?>

Local Product Search Parameters
$lat - User latitude
$long - User longitude
$dist - Max radius from coordinates to search
$max - Maximum number of stores to return
$term - A search term 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 PHP Array:

Array
(
    [0] => Array
        (
            [retailer_store_id] => 1141489
            [aisle411_store_nbr] => 00000
            [retailer_store_nm] => Sample Stores
            [vendor_store_nbr] => 1
            [pla_enabled_flg] => 1
            [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] => Array
                (
                )

            [map] => 1
        )

)

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.

<?php
//function shoppingListSearch($lat, $long, $store_id, $shop_list){
print_r($tool->shoppingListSearch(38.6256740, -90.1892740, 1141489, $list));
?>

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

<?php
//You can build a shopping list like this, filling as many items as you have.
$shop_list = Array();
$shop_list['name'] = 'mylist';
$shop_list['items'] = Array();
$items = Array('milk', 'apple', 'juice', 'cookies', 'tomatoes', 'beer', 'paper');
foreach ($items as $item){
    $shop_list['items'][] = Array('name'=>rawurlencode($item));
}
//When finished, just pass in the array as the final parameter of shoppingListSearch
print_r($tool->shoppingListSearch(38.6256740, -90.1892740, 1141489, $shop_list));
?>
Note: Building a json shopping list is as simple as making an $array with keys: ['name', 'items'] and populating items with $itemexample['name'=>'someproduct'] 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 PHP Array:
Array
(
    [name] => mylist
    [shopping_list_mapping_info] => Array
        (
            [retailer_store_id] => 1141489
            [timestamp] => 2017-08-19T10:54:23-05:00
        )

    [items] => Array
        (
            [0] => Array
                (
                    [synonym_id] => 84535
                    [synonym_nm] => milk
                    [name] => milk
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1075258
                                    [map_location_id] => 24397943
                                    [item_sub_location_id] => 40157579
                                    [aisle] => Dairy
                                    [section] => dairy
                                )

                        )

                )

            [1] => Array
                (
                    [synonym_id] => 259243
                    [synonym_nm] => apples
                    [name] => apple
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1075255
                                    [map_location_id] => 24397875
                                    [item_sub_location_id] => 40157574
                                    [aisle] => Produce
                                    [section] => Fruits
                                )

                        )

                )

            [2] => Array
                (
                    [synonym_id] => 9994
                    [synonym_nm] => juice
                    [name] => juice
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1026277
                                    [map_location_id] => 24397912
                                    [item_sub_location_id] => 40157542
                                    [aisle] => 9
                                    [section] => apple juice
                                )

                        )

                )

            [3] => Array
                (
                    [synonym_id] => 222727
                    [synonym_nm] => cookies
                    [name] => cookies
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1026276
                                    [map_location_id] => 24397916
                                    [item_sub_location_id] => 40157553
                                    [aisle] => 8
                                    [section] => snacks
                                )

                        )

                )

            [4] => Array
                (
                    [synonym_id] => 247511
                    [synonym_nm] => tomatoes
                    [name] => tomatoes
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1075255
                                    [map_location_id] => 24397869
                                    [item_sub_location_id] => 40157575
                                    [aisle] => Produce
                                    [section] => Vegetables
                                )

                        )

                )

            [5] => Array
                (
                    [synonym_id] => 20658
                    [synonym_nm] => beer
                    [name] => beer
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1026268
                                    [map_location_id] => 24397940
                                    [item_sub_location_id] => 40157571
                                    [aisle] => 0
                                    [section] => beer
                                )

                        )

                )

            [6] => Array
                (
                    [synonym_id] => 12600
                    [synonym_nm] => paper
                    [name] => paper
                    [sections] => Array
                        (
                            [0] => Array
                                (
                                    [item_location_id] => 1026278
                                    [map_location_id] => 24397911
                                    [item_sub_location_id] => 40157530
                                    [aisle] => 10
                                    [section] => office supplies
                                )

                        )

                )

        )

)

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.

<?php
//function getPartnerStore($lat, $long, $store_id)
$results = $aisle->getPartnerStore(38.624691, -90.1847763, 209);
?>

Get Partner Store Parameters
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 PHP Array:

Array
(
    [stores] => Array
        (
            [0] => Array
                (
                    [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


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.

<?php
//function getStoreMap($lat, $long, $store_id)
$results = $aisle->getStoreMap(38.624691, -90.1847763, 284);
?>

Get Store Map Parameters
lat - User latitude
$long - User longitude
$storeid - Retailer store id