README

A PHP Client for the Tesco Supermarket API

Contents

• Getting Started
  • Installation
  • Requirements
  • API Key
  • Simple Example
• Usage
  • Requests
    • Grocery Request
    • Product Request
    • Store Location Request
  • Responses
  • Models

Getting Started

Installation

To install, simply require the package using composer:

composer require imclarky/tesco-api

Requirements

• PHP >7.1
• Tesco API Key (see below)

API Key

You will first need to register for an API Key from Tesco's Developer Portal, by signing up for an account and subscribing the General APIs.

Simple Example

Here is a simple example of a request to the Tesco API to find grocerys related to the word chocolate:

$tesco = new \ImClarky\TescoApi\TescoApi('apikey');

$results = $tesco->newGroceryRequest()->addSearchTerm('chocolate')->send();

foreach ($results->getModels() as $grocery) {
    echo $grocery->getName();
}

Usage

Requests

There are two ways of creating requests to the API. The first, as shown above, is to use the base TescoApi class.

The base class is initialized with your API Key:

$tescoApi = new \ImClarky\TescoApi\TescoApi('apikey');

This base class has 3 main functions, each of which will return a new instance of the related request class.

public function newGroceryRequest(): GroceryRequest
{
    return new GroceryRequest($this->_apiKey);
}

public function newProductRequest(): ProductRequest
{
    return new ProductRequest($this->_apiKey);
}

public function newStoreLocationRequest(): StoreLocationRequest
{
    return new StoreLocationRequest($this->_apiKey);
}

Alternatively you can create new instances of the Request classes directly, again passing the API key asa a parameter.

$groceryRequest = new \ImClarky\TescoApi\Requests\GroceryRequest('apikey');

$productRequest = new \ImClarky\TescoApi\Requests\ProductRequest('apikey');

$storeLocationRequest = new \ImClarky\TescoApi\Requests\StoreLocationRequest('apikey');

Each request object has different methods to add query paramters to the API request.

Grocery Request

addSearchTerm(string $searchTerm)
Add a search term to search for. Providing a search term is required; if no term is added when the request is sent, the Request class will throw a RequestException.

$request = new GroceryRequest('apikey');

$response = $request->addSearchTerm('biscuits')->send();

Product Request

addGtin(string $gtin)
Add a product's GTIN/EAN-13 number to the search list.

addTpnb(string $tpnb)
Add a product's Tesco Product Number Base (TPNB) number to the search list.

addTpnc(string $tpnc)
Add a product's Tesco Product Number Consumer (TPNC) number to the search list.

addCatId(string $catId)
Add a product's Catalogue ID to the search list.

Each of these functions returns the request object instance to allow chaining the above methods.

$request = new ProductRequest('apikey');

$response = $request->addGtin('0332322384993')
                    ->addGtin('0368604930293')
                    ->addTpnc('34029384')
                    ->send();

Store Location Request

addSort(string $type, string $value)
Add a Sort query parameter. Currently the only sort type is Near; Which sorts the results by distance from the given location.

addFilter(string $type, $value)
Add a Filter query parameter to filter the results.

Normally a string will be passed in the $value parameter - this will add the term and will be used in a AND expression in the where clause. However, if an array is passed, the values of the array will be treated as an OR expression. For example:

$response = $storeRequest->addFilter(Filter::FILTER_FACILITY, Facility::FACILITY_ATM)
                         ->addFilter(Filter::FILTER_FACILITY, Facility::FACILITY_DBT)
                         ->addFilter(Filter::FILTER_FACILITY, [
                             Facility::FACILITY_CAR_WASH,
                             Facility::FACILITY_JET_WASH,
                             Facility::FACILITY_HAND_CAR_WASH
                         ]);

// In an SQL-like querying language
// WHERE Facility = 'ATM' AND Facility = 'DBT' AND (Facility = 'Car Wash' OR Facility = 'Jet Wash' OR Facility = 'Hand Car Wash')

addLike(string $type, $value, bool $start = false)
Add a Like query paramter to filter the results. This is exactly the same as Filters, except the API will do a full text search for the the value. If $start is set to true, the search will only return results where the term is at the start.

Pagination

Both the Store Location and Grocery request results are returned in pages. You can set the offset and limit on these request, as well as navigate the pages.

setLimit(int $limit)
Set the limit of the request - ie, how many results to return. If this function is never called, then the default value of 10 is used.

setOffset(int $offset)
Set the offset of the request - ie, how many results to offset. If this function is never called, then the default value of 0 is used.

getNextPage()
Get the next page of results

getPrevPage()
Get the previous page of results.

goToPage(int $page)
Go to a specific page of results.

Responses

Each successful request will return a related response object. Eg a StoreLocationRequest returns a StoreLocationResponse. Each response object will contain information like response headers, response status, etc. as well as the models generated from the response data (see below).

Models

Models are generated from the responsed data retrieved from a request.

Grocery

Product

Store

Opening Times and Exceptions

Facility

Guideline Daily Amounts (GDAs)

Nutrition