Store Location

API change history

Search

When performing a search, you can use four optional parameters to control the results: Offset, Limit, Sort and Filter.

If you omit all of them you will get ten (to all intents and purposes) random locations returned!

Offset and Limit

The default values are 0 and 10 (i.e. the first results that match the filter/sort will be returned up to a maximum of 10).

Sort

As you might expect, this sorts the results! Currently the only type of sort supported is by distance from a supplied location. The syntax is sort=near"{location}" where location can be a postcode or place name.

A couple of gotchas that you don't want to be trapped by

  1. The quotes around the placename are optional. However if you ommit them the parser will ignore everything after the first space. e.g.
  2. near:"SW8 4YY" returns locations nearest to the centroid of SW8 4YY.

    near:SW8 4YY returns locations nearest to the centroid of SW8, which could be several miles off.

  3. The geolocator we use is global and in principle may return results from any country.

If your product relates to a single country, it is safest to pass this as part of the location (e.g. near:"Hertford, UK").

At the time of writing, a search for near:"Hertford" returns stores nearest to Hertford, CT (which as it happens are in Northern Ireland).

Examples

sort=near:"SW8 5YY, UK", sort=near:"Welwyn Garden City, UK", sort=near:"London, UK"

Filter

Syntax

To filter by a single condition use {propertyName}:{propertyValue}.

To combine conditions that all must be met sepatate by AND - {propertyName1}:{propertyValue1} AND {propertyName2}:{propertyValue2} AND {propertyName3}:{propertyValue3}

To filter for a property having one of a number of values use a comma separated list - {propertyName}:{propertyValue1},{propertyValue2}.

Properties that can be used in a filter

Property Description
Name The name of the location
branchNumber A legacy branch number e.g. 2055
isoCountryCode An iso 2 character country code e.g. gb. Or one of our accepted aliases e.g. x-uk (see below)
facilities A facility name
category Location category e.g. Store
type Location type e.g. Extra
status Location current status e.g. Trading

Examples

All GB Stores with DBT isoCountryCode:GB AND category:Store AND facilities:DBT

All Stores with DBT and an ATM category:Store AND facilities:DBT AND facilities:ATM

All Stores with DBT and/or an ATM category:Store AND facilities:DBT,ATM

All UK and IOM Stores and CFCs with DBT category:Store,CFC AND facilities:DBT AND isoCountryCode:GB,IM

Like

The Like parameter is similar to Filter, but does a full text search and matches based on a partial value (e.g. stores whose name includes the keyword "Baldock"). The same properties can be used in a Like filter as in a Filter, with the exception of Branch Number (because it is an integer).

For performance reasons, please use Filter instead when you want an exact match. You can use both a Filter and a Like parameter in the same query.

Syntax

The syntax is similar that for Format.

No wildcard pattern is required, you just need to pass the term for which you need to search.

If the term is preceded by a ^ character it will only return matches where the keyword is at the start of the value.

Like terms are case insensitive.

Examples

Query Returns
...search?like=name:Baldock Locations with the word "baldock" in the name
...search?like=name:^Baldock Locations with the word "baldock" at the start of the name
...search?like=name:^Ba Locations with the characters "ba" at the start of the name (could be used for search as you type
...search?like=facilities:click Locations that have a facility that has "click" in the name (Click and Collect presumably...
...search?like=name:Baldock AND facilities:atm Locations with "baldock" in the name that have a facility with "atm" in the name
...search?like=name:Baldock&filter=facilities:atm Locations with "baldock" in the name that have ATMs. Functionally not that different from the previous example but will perform better so use this pattern when you know the full value of a property

Fields

Use this property to limit the location properties returned in the response. Properties should be specified using a comma separated list.

The location's Id (i.e. UUID) will always be returned, as will (currently) any properties associated with the search rather than the location (e.g. "distance from").

e.g.

fields=name,altIds.branchNumber will result in Id, Name and Branch Number only being returned.

Country codes

The region.isoCountryCode property of a location will always be an ISO 3166-1 alpha-2 code.

Where a country code is passed-in to a request in the path or a filter, we accept either a country code or one of the following aliases:

Alias Equivalent to Meaning
x-uk gb AND im AND je AND gg UK as commonly interpreted at Tesco, i.e. the UK plus Isle of Man and Channel Islands

Try it

Request

Request URL

Request parameters

  • (optional)
    number
  • (optional)
    number
  • (optional)
    string
  • (optional)
    string
  • (optional)
    string

Request headers

  • string
    Subscription key which provides access to this API. Found in your Profile.

Request body

Code samples

@ECHO OFF

curl -v -X GET "https://dev.tescolabs.com/locations/search?offset={number}&limit={number}&sort={string}&filter={string}&like={string}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            // Request parameters
            queryString["offset"] = "{number}";
            queryString["limit"] = "{number}";
            queryString["sort"] = "{string}";
            queryString["filter"] = "{string}";
            queryString["like"] = "{string}";
            var uri = "https://dev.tescolabs.com/locations/search?" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://dev.tescolabs.com/locations/search");

            builder.setParameter("offset", "{number}");
            builder.setParameter("limit", "{number}");
            builder.setParameter("sort", "{string}");
            builder.setParameter("filter", "{string}");
            builder.setParameter("like", "{string}");

            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "offset": "{number}",
            "limit": "{number}",
            "sort": "{string}",
            "filter": "{string}",
            "like": "{string}",
        };
      
        $.ajax({
            url: "https://dev.tescolabs.com/locations/search?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://dev.tescolabs.com/locations/search";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"offset={number}",
                         @"limit={number}",
                         @"sort={string}",
                         @"filter={string}",
                         @"like={string}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://dev.tescolabs.com/locations/search');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'offset' => '{number}',
    'limit' => '{number}',
    'sort' => '{string}',
    'filter' => '{string}',
    'like' => '{string}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
    # Request parameters
    'offset': '{number}',
    'limit': '{number}',
    'sort': '{string}',
    'filter': '{string}',
    'like': '{string}',
})

try:
    conn = httplib.HTTPSConnection('dev.tescolabs.com')
    conn.request("GET", "/locations/search?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'offset': '{number}',
    'limit': '{number}',
    'sort': '{string}',
    'filter': '{string}',
    'like': '{string}',
})

try:
    conn = http.client.HTTPSConnection('dev.tescolabs.com')
    conn.request("GET", "/locations/search?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://dev.tescolabs.com/locations/search')

query = URI.encode_www_form({
    # Request parameters
    'offset' => '{number}',
    'limit' => '{number}',
    'sort' => '{string}',
    'filter' => '{string}',
    'like' => '{string}'
})

if uri.query && uri.query.length > 0
    uri.query += '&' + query
else
    uri.query = query
end

request = Net::HTTP::Get.new(uri.request_uri)
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body