API

API possibilities

Shopping-time.ca offers a private API to editors & developpers who wants to integrate our informations into their website, service or mobile application. Our API provides (non exhaustive) :

  • POI lists around a location
  • POI lists for one category, by regional restriction
  • POI lists for a given retail store group
  • Retail store groups with full details
  • Regional subdivision for a country
  • Categories
  • Zip codes
  • Full city list
  • List of open stores, for a specific category, around a GPS point
  • Etc...
  • NEW : POI add & edit

API activation

You need to be logged-in to have access to our API. Login or register an account.

API terms & conditions

Opening hours are not fully available through our API, we only provide an image tag to display a classic table of hours on your service.

Anytime you display a result from our API, we ask you to add a return link to this result specific page's on our website.

This API must be used to provide a list of POI (eg. search engine results OR simple list of POIs onto your pages). This API MUST NOT be used to provide a static page for a POI except on mobile application.

You must not save API's data (as they can change without notice), nevertheless a short cache data is allowed (eg. 24 hours).

Any use of this API must fullfill there terms & conditions. These conditions may vary at any time and we keep the right of temporarly or permanently remove your access to this API.

Documentation

You can access our API through this URL :

/api

Required parameters

key API key registered
h Control hashtag
get Return type. Possible values :
shop(id) : Retun information about one POI
shops(...) : Return a POI list
group(id) : Return information about one group
groups : Return groups list
departements : Return country subdivision (counties, states, etc)
categories : Return website categories
cities(loc) : Return city list
add : Add a POI
edit(id, ...) : Edit a POI

Api - Get Shop - Details

Allow you to get full informations about a POI when you know its ID

id POI ID - required
POI ID that you request informations

Api - Get Shops - Details

At least one parameters or couple of parameters is required for this request : lat/lng, dep, group, cat

lat Latitude - required if you precise a longitude
Allow you to define a center for your request
lng Longitude - required if you precise a latitude
Allow you to define a center for your request
dep Subdivision ID (county, state)
Narrow your search to a specific country subdivision
group Group ID
Narrow your search to a specific group of stores
cat Category or subcategory ID (Example : 3 ; 3_4 ; 5_1 ; 6)
Narrow your search to one or more categories. Concatenate the categories with a pipe (|) - Example : 3|3_4|5_1
name Narrow your search to POI having this specific string in their name
loc Narrow your search around a specific city
Handle a ZIP code or city name. Ideally : input a city + zip code within brackets.
Example : Paris (75001)
open 1 : Narrow your search to currently open POIs
24 : Narrow your search to POIs opens 24h/24
distance Range : 1 to 100 : Narrow your search around a previously specifid point
Require a latitude + longitude
order Possible value : distance
Sort your request by distance. Require a latitude + longitude
offset Range : 0 to 99 : Specify the offset of results you want.
res Range : 1 to 100 : Specify the maximum number of results you want in your request

Api - Get Cities - Details

Return a list of cities from our database

loc Zip code or City name - require
Handle a zip code or a city name. Ideally specify both
Example : Paris (53000)
extended 0 or 1
1 (default) = Enlarge your request to cities containing specified string
0 = Narrow your request to cities beginning by specified string

Api - Add / Edit - Details

Allow you to add or edit POI details.
Edit mode : only specified parameters will be updated. Warning : a key with empty value will set this property as empty. If data doesn't change, don't fill the key.
Use GET or POST mode but POST is advised to prevent URL length problems.

id POI ID - require for edit, passed in URL (GET)
name POI Name - required for add
address Adresse (rue et complément) du commerce - required for add
city City ID matched with API - required for add
cat POI category(ies) - required for add
To precise multiple categories, reference an array (cat[])
group Group ID matched with API - optional
phone POI phone number - optional
lat Latitude (celsius degrees) - optional (required if longitude)
lon Longitude (celsius degrees) - optional (required if latitude)
pmr 0 ou 1 - Access available to weelchairs / PMR - optional
wifi 0 ou 1 - Free wifi access - optional
freepark 0 ou 1 - Free car park - optional
description POI description - optional
Opening hours
Add or update of opening hours must fit to our specific format, please fullfill it.
Either the POI is open 24/24, either opening hours must be given
o2424 0 or 1
Define a POI as open 24/24 - If empty or 0 : Opening hours must be given - Optional for updates
Periods
A period is a table of opening hours. Each period has a title (optional) and N opening windows. Examples : Monday 8h - 18h = 1 opening window ; Tuesday 8h - 12h30 , 14h - 18h = 2 opening windows.
Here how to fill in :
periods[N][title] Title of N period - optional
periods[N][T][day] 1 (Monday) to 7 (Sunday) - Day of opening window T for period N
periods[N][T][from_h] 0 to 23 - Hour of beginning of opening window T for period N
periods[N][T][from_m] 0 to 59 (minutes) - Minute of beginning of opening window T for period N
periods[N][T][to_h] 0 to 32 (8am the next morning) - Hour of end of opening window T for period N
periods[N][T][to_m] 0 to 59 (minutes) - Minute of end of opening window T for period N
Example
A POI open from Monday to Friday, 8h to 17h :
periods[0][0][day]=1
periods[0][0][from_h]=8
periods[0][0][to_h]=17
periods[0][1][day]=2
periods[0][1][from_h]=8
periods[0][1][to_h]=17
periods[0][2][day]=3
periods[0][2][from_h]=8
periods[0][2][to_h]=17
periods[0][3][day]=4
periods[0][3][from_h]=8
periods[0][3][to_h]=17
periods[0][4][day]=5
periods[0][4][from_h]=8
periods[0][4][to_h]=17
Example
A POI open only on Saturday from 11h to 14h30 and then from 18h30 to 2h in the morning :
periods[0][0][day]=6
periods[0][0][from_h]=11
periods[0][0][to_h]=14
periods[0][0][to_m]=30
periods[0][1][day]=6
periods[0][1][from_h]=18
periods[0][1][from_m]=30
periods[0][1][to_h]=26


Usage examples

Groups list

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=groups

Categories list

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=categories

Informations about a specific POI

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=shop&id=1234

POI list around a specific point

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=shops&lat=48.65&lng=1.25&res=10

Cities list containing "Laval"

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=cities&loc=Laval

Cities with zip code 33500

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=cities&loc=33500

Bakeries open in a subdivision

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=shops&dep=35&open=1&cat=2_4

Closest post office open near a current position

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=shops&group=9&open=1&lat=48.65&lng=1.25&order=distance

POI list of retail stores for women and mens around a position in the subdivision

/api?key=YOUR_KEY&h=YOUR_HASHTAG&get=shops&dep=35&cat=10_1|10_3&lat=48.08&lng=-1.68&order=distance

Note about data returned through the API

Datas returned are partial extracts from our database, they can't be considered as certified nor completely correct. Use them with knowledge.