épiceries.ca — API pour développeurs

L'API d'épiceries.ca est publique, en lecture seule et renvoie du JSON. Aucune clé ni authentification n'est requise : il suffit d'une requête GET. Les réponses incluent les en-têtes CORS, vous pouvez donc l'appeler directement depuis un navigateur. La base de tous les appels est :

https://epiceries.ca/api

Introduction

Chaque réponse suit la même enveloppe. En cas de succès :

{ "ok": true, "data": { ... } }

En cas d'erreur (avec un code HTTP correspondant) :

{ "ok": false, "error": { "code": "not_found", "message": "..." } }

Format : JSON (UTF-8). Ajoutez &pretty=1 à n'importe quel appel pour une sortie indentée, pratique dans le navigateur.
Méthode : GET uniquement. Les paramètres passent par la chaîne de requête (?clé=valeur).
CORS : Access-Control-Allow-Origin: * — utilisable depuis un site tiers ou une application.
Cache : les réponses sont mises en cache 5 minutes (Cache-Control: public, max-age=300). Les prix sont rafraîchis chaque semaine.

Usage raisonnable. Ce service est offert gratuitement. Merci de mettre vos résultats en cache, d'éviter les rafales de requêtes et de rester sous quelques requêtes par seconde. Pour un usage intensif, écrivez-nous à [email protected].

Concepts

Identifiant de produit (`id`)

Chaque produit possède un identifiant alphanumérique court — par exemple a1b2c3. C'est la clé utilisée par les endpoints product et history, et c'est aussi ce qui apparaît dans l'URL d'une fiche produit : https://epiceries.ca/view?i=a1b2c3. Obtenez-le via search ou barcode.

Magasins

Six enseignes sont suivies. La valeur store est toujours l'une de :

maxi · iga · superc · metro · provigo · walmart

Prix unitaire

Lorsqu'il est connu, unitPrice ramène le prix à une mesure comparable : { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" }. value peut être null si le format n'a pas pu être analysé ; unit vaut « 100 g », « 100 ml », « m » ou « unité ».

Dates

Les points d'historique portent deux champs : timestamp (secondes Unix, UTC) et date (chaîne IS 8601). Les paramètres from/to acceptent l'un ou l'autre format.

Essayer l'API

Choisissez un endpoint, ajustez la chaîne de requête, puis lancez l'appel. La requête part vers cette instance.

/api?

Prêt.

// La réponse s'affichera ici.

GET /api

Point d'entrée auto-descriptif : renvoie la version, la liste des magasins et des endpoints. Utile pour vérifier que tout répond.

Réponse

{
  "ok": true,
  "data": {
    "name": "épiceries.ca API",
    "version": "1",
    "documentation": "https://epiceries.ca/developers",
    "stores": ["maxi", "iga", "superc", "metro", "provigo", "walmart"],
    "endpoints": { "search": "...", "product": "...", "history": "...", "barcode": "...", "categories": "..." }
  }
}

GET /api?endpoint=search

Recherche de produits par texte, catégorie, rabais et/ou magasin le moins cher. Fournissez au moins un filtre. Chaque résultat contient les valeurs actuelles du produit.

Paramètre	Type		Description
q	texte	optionnel	Terme recherché (nom ou marque), 2 caractères minimum.
category	entier	optionnel	Identifiant de catégorie (1–71), voir `categories`.
discounted	booléen	optionnel	`true` pour ne garder que les produits en rabais.
store	texte	optionnel	Ne garder que les produits dont le magasin le moins cher est celui-ci.
sort	texte	optionnel	`updated_desc` (défaut), `price_asc` ou `price_desc`.
limit	entier	optionnel	Nombre de résultats, 1–100 (défaut 20).
offset	entier	optionnel	Décalage pour la pagination (défaut 0).

Exemple de requête

GET /api?endpoint=search&q=lait&sort=price_asc&limit=2

Réponse

{
  "ok": true,
  "data": {
    "count": 2,
    "limit": 2,
    "offset": 0,
    "hasMore": true,
    "results": [
      {
        "id": "a1b2c3",
        "name": "Lait 2% partiellement écrémé",
        "brand": "Québon",
        "size": "2 L",
        "price": 4.99,
        "unitPrice": { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" },
        "store": "maxi",
        "discounted": false,
        "category": 12,
        "image": "https://cdn.epiceries.ca/quebon-lait-2.jpg",
        "link": "https://www.maxi.ca/...",
        "url": "https://epiceries.ca/view?i=a1b2c3",
        "updated": "2026-07-02T09:14:00+00:00"
      }
    ]
  }
}

hasMore indique s'il reste des résultats au-delà de la page courante ; augmentez offset pour les obtenir.

GET /api?endpoint=product&id=PRODUCT_ID

Les valeurs actuelles d'un produit, plus le dernier prix relevé dans chaque magasin (tableau prices). Les magasins sans données sont omis.

Paramètre	Type		Description
id	texte	requis	Identifiant de produit (voir Concepts).

Exemple de requête

GET /api?endpoint=product&id=a1b2c3

Réponse

{
  "ok": true,
  "data": {
    "id": "a1b2c3",
    "name": "Lait 2% partiellement écrémé",
    "brand": "Québon",
    "size": "2 L",
    "price": 4.99,
    "unitPrice": { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" },
    "store": "maxi",
    "discounted": false,
    "category": 12,
    "image": "https://cdn.epiceries.ca/quebon-lait-2.jpg",
    "link": "https://www.maxi.ca/...",
    "url": "https://epiceries.ca/view?i=a1b2c3",
    "updated": "2026-07-02T09:14:00+00:00",
    "prices": [
      { "store": "maxi", "price": 4.99, "discounted": false, "size": "2 L",
        "unitPrice": { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" },
        "link": "https://www.maxi.ca/...", "timestamp": 1751447640, "date": "2026-07-02T09:14:00+00:00" },
      { "store": "iga", "price": 5.49, "discounted": false, "size": "2 L",
        "unitPrice": { "value": 0.27, "unit": "100 ml", "raw": "0.27/100ml" },
        "link": "https://www.iga.net/...", "timestamp": 1751447280, "date": "2026-07-02T09:08:00+00:00" }
    ]
  }
}

Le champ store de premier niveau est le magasin le moins cher ; price est son prix.

GET /api?endpoint=history&id=PRODUCT_ID

La série historique des prix d'un produit, du plus ancien au plus récent (idéal pour tracer un graphique). Filtrez par magasin et/ou par fenêtre de dates.

Paramètre	Type		Description
id	texte	requis	Identifiant de produit.
store	texte	optionnel	Limiter à un seul magasin. Sinon, tous les magasins sont inclus.
from	date	optionnel	Borne inférieure : timestamp Unix ou date ISO 8601.
to	date	optionnel	Borne supérieure : timestamp Unix ou date ISO 8601.
limit	entier	optionnel	Nombre de points les plus récents, 1–500 (défaut 100).

Exemple de requête

GET /api?endpoint=history&id=a1b2c3&store=maxi&limit=3

Réponse

{
  "ok": true,
  "data": {
    "id": "a1b2c3",
    "store": "maxi",
    "count": 3,
    "history": [
      { "store": "maxi", "price": 5.49, "discounted": false, "size": "2 L",
        "unitPrice": { "value": 0.27, "unit": "100 ml", "raw": "0.27/100ml" },
        "link": "https://www.maxi.ca/...", "timestamp": 1748855640, "date": "2026-06-02T09:14:00+00:00" },
      { "store": "maxi", "price": 4.99, "discounted": true, "size": "2 L",
        "unitPrice": { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" },
        "link": "https://www.maxi.ca/...", "timestamp": 1750065240, "date": "2026-06-16T09:14:00+00:00" },
      { "store": "maxi", "price": 4.99, "discounted": false, "size": "2 L",
        "unitPrice": { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" },
        "link": "https://www.maxi.ca/...", "timestamp": 1751447640, "date": "2026-07-02T09:14:00+00:00" }
    ]
  }
}

GET /api?endpoint=barcode&code=BARCODE

Résout un code-barre (UPC/EAN) vers le produit correspondant, avec un résumé du produit courant.

Paramètre	Type		Description
code	chiffres	requis	Code-barre numérique de 8 à 14 chiffres.

Réponse

{
  "ok": true,
  "data": {
    "barcode": "0687456301234",
    "id": "a1b2c3",
    "url": "https://epiceries.ca/view?i=a1b2c3",
    "product": {
      "id": "a1b2c3", "name": "Lait 2% partiellement écrémé", "brand": "Québon",
      "size": "2 L", "price": 4.99, "store": "maxi", "discounted": false,
      "unitPrice": { "value": 0.25, "unit": "100 ml", "raw": "0.25/100ml" }
    }
  }
}

product reprend les mêmes champs que search. Pour le détail par magasin, enchaînez avec product en utilisant l'id renvoyé.

GET /api?endpoint=storeproduct&store=maxi&code=STORE_CODE

Résout le code produit propre à un magasin — le {code} d'une fiche .../p/{code} (p. ex. Maxi 20021564_EA) — vers le produit épiceries.ca, et renvoie en un seul appel : le résumé du produit, le dernier prix relevé dans chaque magasin (product.prices), le verdict « vrai rabais » pour ce magasin (deal) et l'historique de prix de ce magasin (history). C'est l'endpoint qui alimente la fiche prix de l'extension navigateur, affichée sur la page produit de l'épicerie.

Paramètre	Type		Description
store	texte	requis	Magasin de la fiche : `maxi`, `iga`, `superc`, `metro`, `provigo` ou `walmart`.
code	texte	requis	Code produit du magasin, tel qu'il apparaît après `/p/` dans l'URL de la fiche.

Exemple de requête

GET /api?endpoint=storeproduct&store=maxi&code=20021564_EA

Réponse

{
	"ok": true,
	"data": {
		"store": "maxi",
		"code": "20021564_EA",
		"id": "a1b2c3",
		"url": "https://epiceries.ca/view?i=a1b2c3",
		"product": {
			"id": "a1b2c3", "name": "Lait 2%", "brand": "Québon", "size": "4 L",
			"price": 6.99, "store": "maxi", "discounted": true,
			"prices": [ { "store": "maxi", "price": 6.99, "discounted": true, "...": "..." } ]
		},
		"deal": {
			"store": "maxi", "score": 2, "label": "Bon rabais",
			"percentileRank": 12, "cheaperThanPercent": 88, "sampleCount": 37,
			"stats": { "latest": 6.99, "min52w": 6.49, "median52w": 7.79, "median26w": 7.49, "max52w": 8.49 }
		},
		"history": [
			{ "store": "maxi", "price": 7.79, "discounted": false, "timestamp": 1748855640, "...": "..." }
		]
	}
}

Le score du deal vaut 3 (Prix plancher), 2 (Bon rabais), 1 (Rabais ordinaire), 0 (Faux rabais) ou null (historique insuffisant), comme le verdict des fiches produit. deal est null lorsque le magasin n'a pas de note calculée.

GET /api?endpoint=categories

La liste des catégories acceptées par le filtre category de search. Aucun paramètre.

Réponse

{
  "ok": true,
  "data": {
    "count": 71,
    "categories": [
      { "id": 3, "name": "Boulangerie" },
      { "id": 12, "name": "Produits laitiers et œufs" },
      { "id": 27, "name": "Viandes" }
    ]
  }
}

Erreurs

Les erreurs renvoient { "ok": false, "error": { "code", "message" } } avec le code HTTP correspondant.

HTTP	code	Signification
200	—	Succès (`ok: true`).
400	bad_request	Paramètre manquant ou invalide.
404	not_found	Produit, code-barre ou endpoint introuvable.
405	method_not_allowed	Méthode autre que `GET`.
500	server_error	Erreur inattendue côté serveur.

Démarrage rapide

curl

curl "https://epiceries.ca/api?endpoint=search&q=lait"

JavaScript (fetch)

const res = await fetch('https://epiceries.ca/api?endpoint=product&id=a1b2c3');
const { ok, data } = await res.json();
if (ok) {
  console.log(data.name, data.price);
  data.prices.forEach(p => console.log(p.store, p.price));
}

Python (requests)

import requests

r = requests.get("https://epiceries.ca/api", params={
    "endpoint": "history",
    "id": "a1b2c3",
    "store": "maxi",
})
data = r.json()["data"]
for point in data["history"]:
    print(point["date"], point["price"])

Conditions

Les prix sont fournis à titre indicatif ; vérifiez toujours en magasin. Les données proviennent des sites des marchands et peuvent comporter des erreurs ou des délais. Merci d'attribuer la source (épiceries.ca) si vous les republiez, et d'en faire un usage raisonnable. Une question ou un projet ? Écrivez-nous : [email protected].

API épiceries.ca

Introduction

Concepts

Identifiant de produit (id)

Magasins

Prix unitaire

Dates

Essayer l'API

Erreurs

Démarrage rapide

Conditions

Identifiant de produit (`id`)