Documentation

Aperçu

L'API AICA Address Autocomplete renvoie des suggestions d'adresses canadiennes structurées pendant la saisie. Utilisez-la depuis votre backend ou via notre widget hébergé. Tout le trafic de production doit utiliser HTTPS.

URL de base :

https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada

Les routes incorrectes ou mal configurées renvoient un JSON qui inclut l’état du service (status, service, note) ainsi que error_code — pas de page santé séparée.

Créer un compte / clé API Ouvrir la démo

Authentification

Les requêtes utilisent votre clé aica_live_. Pour le widget, la clé est dans le navigateur et doit être restreinte par domaine. Pour le serveur, gardez la clé uniquement côté backend.

X-AICA-API-Key: aica_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer aica_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Clé en paramètre d’URL (serveur / backend)

Vous pouvez aussi passer la clé avec ?api_key= sur une URL GET standard. Préférez l’en-tête X-AICA-API-Key lorsque c’est possible. Utilisez uniquement une clé serveur — jamais dans une page navigateur. Les clés dans les URL peuvent apparaître dans les journaux de proxy et l’historique du navigateur.

https://aica-apis.quebecstore.ca/v1/address/autocomplete?search=123%20main&api_key=YOUR_API_KEY

Clé manquante → HTTP 401, AICA-E002. Codes d'erreur.

Widget = clé navigateur + domaines autorisés (style AddressComplete). Serveur = clé secrète. Préférez des clés séparées.

Widget intégré

Ajoutez un script CDN et un div vide. Mettez votre clé aica_live_ sur le div (data-api-key). Autorisez votre domaine dans le tableau de bord — aucun proxy PHP requis.

1. Installation en un script (recommandé)

Ajoutez ce script unique dans le head de la page (ou avant la balise body de fermeture). aica-loader.js injecte le CSS une fois et charge le widget. Pas de aica-proxy.php. Restreignez la clé à vos domaines dans la gestion des clés.

<script src="https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada/interactive/aica-loader.js" async></script>

1.A Monter le champ de recherche

Placez ce div vide là où la recherche d’adresse doit apparaître (paiement, facturation, contact). Mettez votre clé aica_live_ dans data-api-key. Le chargeur de l’étape 1 trouve automatiquement chaque div data-aica-autocomplete.

<div id="address-field"
     data-aica-autocomplete
     data-api-key="aica_live_YOUR_KEY_HERE"></div>

Page exemple : checkout.html

Mise en page checkout complète avec l’installation recommandée (loader + montage + champs autofill). Affichez le code coloré ou téléchargez le fichier.

Télécharger checkout.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Secure Checkout</title>
    <!-- AICA: use <script src="…aica-loader.js"> — do not iframe / embed AICA HTML.
         CSP must allow https://aica-apis.quebecstore.ca (script, style, img, connect).
         Allowlist this page's domain on the widget API key. -->
    <script src="https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada/interactive/aica-loader.js" async></script>
    <style>
        :root {
            --primary: #2563eb;
            --bg: #f8fafc;
            --card-bg: #ffffff;
            --text: #1e293b;
            --border: #e2e8f0;
        }
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
            background-color: var(--bg);
            color: var(--text);
            margin: 0;
            padding: 20px;
        }
        .checkout-container {
            max-width: 1100px;
            margin: 0 auto;
            display: grid;
            grid-template-columns: 1fr;
            gap: 30px;
        }
        @media (min-width: 768px) {
            .checkout-container {
                grid-template-columns: 1.6fr 1fr;
            }
        }
        .panel {
            background: var(--card-bg);
            padding: 30px;
            border-radius: 8px;
            box-shadow: 0 1px 3px rgba(0,0,0,0.1);
        }
        h2 {
            margin-top: 0;
            margin-bottom: 20px;
            border-bottom: 2px solid var(--border);
            padding-bottom: 10px;
            font-size: 1.5rem;
        }
        .form-group {
            margin-bottom: 18px;
        }
        .form-row {
            display: grid;
            grid-template-columns: 1fr;
            gap: 15px;
        }
        @media (min-width: 480px) {
            .form-row.three-col {
                grid-template-columns: 2fr 1fr 1fr;
            }
        }
        label {
            display: block;
            margin-bottom: 6px;
            font-weight: 500;
            font-size: 0.9rem;
        }
        input[type="text"], input[type="email"] {
            width: 100%;
            padding: 10px;
            border: 1px solid var(--border);
            border-radius: 6px;
            box-sizing: border-box;
            font-size: 1rem;
        }
        input:focus {
            outline: none;
            border-color: var(--primary);
            box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.15);
        }
        #aica-search-wrapper {
            margin-bottom: 20px;
            padding: 15px;
            background: #f1f5f9;
            border-radius: 6px;
            border: 1px dashed #cbd5e1;
        }
        .summary-item {
            display: flex;
            justify-content: space-between;
            margin-bottom: 12px;
        }
        .total {
            font-weight: bold;
            font-size: 1.2rem;
            border-top: 2px solid var(--border);
            padding-top: 12px;
            margin-top: 12px;
        }
        .btn-submit {
            background-color: var(--primary);
            color: white;
            border: none;
            width: 100%;
            padding: 14px;
            font-size: 1.1rem;
            font-weight: bold;
            border-radius: 6px;
            cursor: pointer;
            margin-top: 20px;
        }
        .btn-submit:hover {
            background-color: #1d4ed8;
        }
    </style>
</head>
<body>

<div class="checkout-container">
    
    <!-- LEFT PANEL: SHIPPING ENTRY -->
    <div class="panel">
        <h2>Shipping & Billing Address</h2>
        <form id="checkout" onsubmit="handleFormSubmit(event)">
            
            <div class="form-row" style="grid-template-columns: 1fr 1fr; gap: 15px; margin-bottom: 18px;">
                <div class="form-group">
                    <label for="first_name">First Name</label>
                    <input type="text" id="first_name" required>
                </div>
                <div class="form-group">
                    <label for="last_name">Last Name</label>
                    <input type="text" id="last_name" required>
                </div>
            </div>

            <div class="form-group">
                <label for="email">Email Address</label>
                <input type="email" id="email" required>
            </div>

            <!-- INTERACTIVE WIDGET COMPONENT -->
            <div id="aica-search-wrapper">
                <label style="color: var(--primary); font-weight: bold;">Search Canadian Address:</label>
                <div 
                    id="address-field" 
                    data-aica-autocomplete 
                    data-api-key="aica_live_YOUR_KEY_HERE" 
                    data-aica-fields-root="#checkout">
                </div>
            </div>

            <!-- TARGET MAPPED FORM INPUTS -->
            <div class="form-group">
                <label for="street">Street Address</label>
                <input type="text" id="street" name="street" data-aica-field="street_line" required placeholder="Type in lookup above...">
            </div>

            <div class="form-row three-col">
                <div class="form-group">
                    <label for="city">City</label>
                    <input type="text" id="city" name="city" data-aica-field="city" required>
                </div>
                <div class="form-group">
                    <label for="province">Province</label>
                    <input type="text" id="province" name="province" data-aica-field="province" required>
                </div>
                <div class="form-group">
                    <label for="postal_code">Postal Code</label>
                    <input type="text" id="postal_code" name="postal_code" data-aica-field="postal_code" required>
                </div>
            </div>

            <button type="submit" class="btn-submit">Complete Purchase</button>
        </form>
    </div>

    <!-- RIGHT PANEL: ORDER SUMMARY -->
    <div class="panel" style="height: fit-content;">
        <h2>Order Summary</h2>
        <div class="summary-item">
            <span>Premium Canadian Service</span>
            <span>$45.00</span>
        </div>
        <div class="summary-item">
            <span>Shipping</span>
            <span style="color: #16a34a; font-weight: 500;">Free</span>
        </div>
        <div class="summary-item total">
            <span>Total (CAD)</span>
            <span>$45.00</span>
        </div>
    </div>

</div>

<script>
    function handleFormSubmit(event) {
        event.preventDefault();
        alert('Order Processed Successfully!');
        
        // Recommended by documentation: Removes data tracing from browser URL on submission
        if (window.history.pushState) {
            const cleanUrl = window.location.protocol + "//" + window.location.host + window.location.pathname;
            window.history.pushState({path: cleanUrl}, '', cleanUrl);
        }
    }
</script>

</body>
</html>

Fin de l’installation recommandée — c’est le chemin que nous voulons pour la plupart des sites.

2. Installation classique (optionnel — plus d’URLs)

CSS + JS explicites + mount() — passez apiKey dans les options. À utiliser seulement si vous ne voulez pas aica-loader.js (ex. CSP strict).

<link rel="stylesheet" href="https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada/interactive/aica-autocomplete.css" />
<script src="https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada/interactive/aica-autocomplete.js"></script>
<script>AicaAutocomplete.mount("#address-field", { apiKey: "aica_live_YOUR_KEY_HERE" });</script>

Remplir les champs du formulaire

Après la sélection finale, AICA peut remplir vos champs existants comme si le visiteur avait saisi l’adresse. Aucun mapping JSON requis. Utilisez data-aica-field ou des alias name/id.

Jetons de champs supportés

result / address / full_address
street_line / street / address1
building_line / building
unit / apt / suite
city
postal_code / postal / zip
province / provice_abbr / state
addr_id
lat / lon
city_prov

<form id="checkout">
  <div id="address-field"
       data-aica-autocomplete
       data-api-key="aica_live_YOUR_KEY_HERE"
       data-aica-fields-root="#checkout"></div>
  <input name="street" data-aica-field="street_line">
  <input name="city" data-aica-field="city">
  <input name="postal_code">
  <input name="province" data-aica-field="province">
</form>
<script src="https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada/interactive/aica-loader.js" async></script>

Le remplissage écrit dans les champs — il ne sert pas à la recherche. Les sites avancés peuvent toujours utiliser le JSON onSelect.

Langue du widget

Le texte indicatif et le compte d’unités suivent d’abord la page hôte : définissez ou (fr-CA, en-US, etc. sont reconnus). Si la page ne déclare pas de langue, le widget utilise la langue du navigateur du visiteur (navigator.languages). Sinon, l’anglais. Bonne pratique : toujours indiquer lang sur la racine du document pour que tous les visiteurs de ce site voient le même texte.

Confidentialité du paramètre URL

Par défaut le widget écrit aussi ?aica_selection= (JSON en base64) dans l’URL. Cette valeur contient des données d’adresse — évitez de partager ces liens, ou effacez le paramètre après enregistrement.

Si le widget s’affiche sans CSS, que la boîte est vide, ou que la saisie n’appelle jamais l’API, corrigez d’abord votre site :

Utilisez une balise <script src="…"> (ou aica-loader.js). N’iframez pas, n’utilisez pas <embed> ni <object> sur nos pages. Le HTML AICA envoie X-Frame-Options: DENY : un iframe restera blanc.
Votre Content-Security-Policy, WAF ou liste de domaines autorisés doit permettre à la page de communiquer avec https://aica-apis.quebecstore.ca — scripts, CSS, images et appels API (script-src, style-src, img-src et connect-src). Bloquer cet hôte = pas de styles et pas d’autocomplétion.
Dans le tableau de bord AICA, ajoutez le domaine exact de la page qui héberge le widget sur cette clé widget (example.com et www.example.com si vous utilisez les deux).

Content-Security-Policy:
  script-src 'self' https://aica-apis.quebecstore.ca;
  style-src 'self' https://aica-apis.quebecstore.ca;
  img-src 'self' https://aica-apis.quebecstore.ca;
  connect-src 'self' https://aica-apis.quebecstore.ca;

Pointer le widget vers votre proxy — Backend par stack

Essayer la démo

Backend par stack

N'exposez jamais votre clé API dans du HTML ou du JavaScript navigateur. Choisissez votre stack ci-dessous — chaque chemin garde la clé côté serveur et pointe le widget vers votre proxy.

Les appels API directement côté serveur (sans proxy accessible au navigateur) sont les plus sécurisés : aucune URL publique à abuser. Utilisez un proxy widget seulement pour l'autocomplétion front-end.

Configuration PHP

1. aica-config.php

Placez-le à côté de aica-proxy.php (ex. public_html/api/). Définissez api_key et site_origin (https://votredomaine.com). Dans le tableau de bord, ajoutez seulement votredomaine.com — www est ajouté automatiquement.

<?php

declare(strict_types=1);

/**
 * AICA API credentials — server-side only. Never expose in HTML or JavaScript.
 *
 * WHERE TO PUT THIS FILE
 * ----------------------
 * Recommended: same folder as aica-proxy.php
 *   your-site/api/aica-config.php
 *   your-site/api/aica-proxy.php
 *
 * Also works (proxy searches automatically):
 *   your-site/aica-config.php
 *   your-site/config/aica-config.php
 *   or set env AICA_CONFIG_PATH=/full/path/to/aica-config.php
 *
 * WIDGET HTML (any page on your site)
 * -----------------------------------
 * <div id="aica-address" data-api-base="/api/aica-proxy.php"></div>
 *
 * The browser JS (hosted by AICA) reads data-api-base and calls:
 *   /api/aica-proxy.php?search=...
 *   /api/aica-proxy.php/units?parent_id=...
 *   /api/aica-proxy.php/session-complete
 *
 * site_origin — your public site URL. The proxy sends this to AICA (never the
 * browser Origin header) so callers cannot spoof your domain.
 */
return [
    'api_key' => 'class="tok-key">aica_live_REPLACE_WITH_YOUR_KEY',
    'api_base' => 'class="tok-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada',
    'site_origin' => 'class="tok-url">https://example.com',
];

2. aica-proxy.php

Le JS du widget appelle ce fichier via data-api-base. Il charge la config dans le même dossier et transmet les requêtes à AICA avec votre clé et un site_origin fixe.

<?php

declare(strict_types=1);

/**
 * AICA Address Autocomplete — server-side proxy for the embed widget.
 *
 * UPLOAD
 * ------
 * Put this file on your PHP host, e.g. public_html/api/aica-proxy.php
 * Put aica-config.php in the same folder (or see loadAicaConfig() below).
 *
 * WIDGET → THIS FILE (browser, from your HTML)
 * --------------------------------------------
 * Your page includes:
 *   <link  href="class="tok-url">https://aica-apis.quebecstore.ca/.../aica-autocomplete.css" />
 *   <div   id="aica-address" data-api-base="/api/aica-proxy.php"></div>
 *   <script src="class="tok-url">https://aica-apis.quebecstore.ca/.../aica-autocomplete.js"></script>
 *   <script>AicaAutocomplete.mount('#aica-address');</script>
 *
 * The widget JS calls data-api-base + query string, for example:
 *   GET /api/aica-proxy.php?search=657
 *   GET /api/aica-proxy.php/units?parent_id=...
 *   GET /api/aica-proxy.php/session-complete
 *
 * Change data-api-base to match where YOU uploaded this file.
 * Examples:
 *   /api/aica-proxy.php
 *   /shop/api/aica-proxy.php
 *   class="tok-url">https://yourdomain.com/api/aica-proxy.php
 *
 * THIS FILE → aica-config.php (server only)
 * -----------------------------------------
 * Loads your API key from aica-config.php (never sent to the browser).
 *
 * DOMAIN TIP
 * ----------
 * In the AICA dashboard add only example.com — www.example.com is added automatically.
 *
 * SECURITY
 * --------
 * Set site_origin in aica-config.php. This proxy sends that fixed Origin to AICA
 * and ignores the browser Origin header (prevents domain spoofing).
 */

/**
 * @return array{api_key: string, api_base: string, site_origin?: string}
 */
function loadAicaConfig(): array
{
    $candidates = array_filter([
        getenv('AICA_CONFIG_PATH') ?: null,
        __DIR__ . '/aica-config.php',
        dirname(__DIR__) . '/aica-config.php',
        dirname(__DIR__) . '/config/aica-config.php',
        isset($_SERVER['DOCUMENT_ROOT']) ? rtrim((string) $_SERVER['DOCUMENT_ROOT'], '/') . '/config/aica-config.php' : null,
    ]);

    foreach ($candidates as $path) {
        if (is_file($path)) {
            $loaded = require $path;
            if (is_array($loaded)) {
                return $loaded;
            }
        }
    }

    return [
        'api_key' => getenv('AICA_API_KEY') ?: '',
        'api_base' => getenv('AICA_API_BASE') ?: 'class="tok-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada',
    ];
}

$config = loadAicaConfig();
$apiKey = (string) ($config['api_key'] ?? '');
$apiBase = rtrim((string) ($config['api_base'] ?? ''), '/');
$siteOrigin = rtrim((string) ($config['site_origin'] ?? ''), '/');

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    header('Access-Control-Allow-Origin: ' . ($_SERVER['HTTP_ORIGIN'] ?? '*'));
    header('Access-Control-Allow-Headers: X-AICA-Session-Id, X-AICA-Interaction-Complete, Content-Type');
    header('Access-Control-Allow-Methods: GET, OPTIONS');
    http_response_code(204);
    exit;
}

if ($apiKey === '' || str_contains($apiKey, 'REPLACE_WITH_YOUR_KEY')) {
    http_response_code(503);
    header('Content-Type: application/json');
    echo json_encode(['error' => 'Proxy not configured — edit api_key in aica-config.php next to this file']);
    exit;
}

if ($siteOrigin === '' || str_contains($siteOrigin, 'example.com')) {
    http_response_code(503);
    header('Content-Type: application/json');
    echo json_encode(['error' => 'Proxy not configured — set site_origin in aica-config.php to your site URL']);
    exit;
}

$uri = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/';
$script = $_SERVER['SCRIPT_NAME'] ?? '';
$suffix = '';

if ($script !== '' && str_contains($uri, $script)) {
    $suffix = substr($uri, strpos($uri, $script) + strlen($script));
}
$suffix = ($suffix === '' || $suffix === '/') ? '' : $suffix;

$allowed = ['', '/session-complete', '/units'];
if (!in_array($suffix, $allowed, true) && !str_starts_with($suffix, '/units')) {
    http_response_code(404);
    header('Content-Type: application/json');
    echo json_encode(['error' => 'Proxy path not found']);
    exit;
}

$query = $_SERVER['QUERY_STRING'] ?? '';
$target = $apiBase . $suffix . ($query !== '' ? '?' . $query : '');

$headers = [
    'Accept: application/json',
    'X-AICA-API-Key: ' . $apiKey,
    'Origin: ' . $siteOrigin,
];
foreach (['HTTP_X_AICA_SESSION_ID', 'HTTP_X_AICA_INTERACTION_COMPLETE'] as $h) {
    if (!empty($_SERVER[$h])) {
        $name = str_replace(' ', '-', ucwords(strtolower(str_replace('HTTP_', '', $h)), '_'));
        $headers[] = $name . ': ' . $_SERVER[$h];
    }
}

$ch = curl_init($target);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_FOLLOWLOCATION => false,
]);
$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

http_response_code($status > 0 ? $status : 502);
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: ' . ($_SERVER['HTTP_ORIGIN'] ?? '*'));
header('Access-Control-Allow-Headers: X-AICA-Session-Id, X-AICA-Interaction-Complete, Content-Type');
echo $body === false ? '{}' : $body;

3. Protéger la config (Apache)

.htaccess optionnel pour empêcher le téléchargement HTTP de aica-config.php.

# .htaccess in api/ — block direct HTTP access to config
<Files "aica-config.php">
    Require all denied
</Files>

4. Pointer le widget vers votre proxy

<div id="address-field" data-api-base="/api/aica-proxy.php"></div>

Configuration Node / Express

Pour hébergement Node. Définissez AICA_API_KEY, AICA_SITE_ORIGIN, montez sur /api/aica-proxy. Le widget utilise le même data-api-base qu'en PHP.

1. Installer avec npm

Dans votre projet Node, puis ajoutez le proxy Express ci-dessous.

npm install express

2. Proxy Express

/**
 * Express widget proxy — same role as api/aica-proxy.php (Node.js / IIS reverse-proxy hosts).
 *
 * Env: AICA_API_KEY, AICA_API_BASE, AICA_SITE_ORIGIN (e.g. https://example.com)
 *
 * Mount: app.use('/api/aica-proxy', aicaProxyRouter);
 * Widget: data-api-base="/api/aica-proxy"
 */
import express from 'express';

const router = express.Router();

const API_KEY = process.env.AICA_API_KEY || '';
const API_BASE = (process.env.AICA_API_BASE || 'https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada').replace(/\/$/, '');
const SITE_ORIGIN = (process.env.AICA_SITE_ORIGIN || '').replace(/\/$/, '');

router.get(/^(?:\/units)?\/?$/, async (req, res) => {
  if (!API_KEY || API_KEY.includes('REPLACE')) {
    return res.status(503).json({ error: 'Proxy not configured — set AICA_API_KEY' });
  }
  if (!SITE_ORIGIN || SITE_ORIGIN.includes('example.com')) {
    return res.status(503).json({ error: 'Proxy not configured — set AICA_SITE_ORIGIN' });
  }

  const suffix = req.path === '/' ? '' : req.path;
  const url = `${API_BASE}${suffix}?${new URLSearchParams(req.query)}`;

  const headers = {
    Accept: 'application/json',
    'X-AICA-API-Key': API_KEY,
    Origin: SITE_ORIGIN,
  };
  if (req.get('x-aica-session-id')) headers['X-AICA-Session-Id'] = req.get('x-aica-session-id');
  if (req.get('x-aica-interaction-complete')) headers['X-AICA-Interaction-Complete'] = req.get('x-aica-interaction-complete');

  const upstream = await fetch(url, { headers });
  const body = await upstream.text();
  res.status(upstream.status).type('application/json').send(body);
});

export default router;

3. Côté serveur uniquement (plus sécurisé)

Appelez AICA depuis votre backend avec la clé API. Aucun proxy navigateur requis. Idéal quand votre propre code PHP/Node gère la recherche.

/**
 * Server-side AICA autocomplete — keep AICA_API_KEY in env only.
 */
export async function searchAddress(query, sessionId) {
  const key = process.env.AICA_API_KEY;
  if (!key) throw new Error('AICA_API_KEY not configured');

  const url = new URL('https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada');
  url.searchParams.set('search', query);

  const res = await fetch(url, {
    headers: {
      'X-AICA-API-Key': key,
      'X-AICA-Session-Id': sessionId,
      Accept: 'application/json',
    },
  });

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(body.error || `AICA ${res.status}`);
  }

  return res.json();
}

4. Pointer le widget vers votre proxy

<div id="address-field" data-api-base="/api/aica-proxy"></div>

Configuration ASP.NET / ASPX

Pour l'écosystème Microsoft (.NET 6+). Même HTML widget sur une page .cshtml ; data-api-base vers /api/aica-proxy. Les sites .aspx legacy peuvent utiliser ASP.NET Core ou un reverse-proxy vers PHP.

// ASP.NET Core minimal API proxy — same role as api/aica-proxy.php (IIS / Azure / Windows hosts).
// Add to Program.cs. Store secrets in appsettings or environment variables.
//
// Widget HTML (any .cshtml / .aspx page):
//   <div id="aica-address" data-api-base="/api/aica-proxy"></div>
//
// Env / appsettings:
//   AICA:ApiKey, AICA:ApiBase, AICA:SiteOrigin

using System.Net.Http.Headers;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var apiKey = builder.Configuration["AICA:ApiKey"] ?? "";
var apiBase = (builder.Configuration["AICA:ApiBase"] ?? "https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada").TrimEnd('/');
var siteOrigin = (builder.Configuration["AICA:SiteOrigin"] ?? "").TrimEnd('/');

app.MapGet("/api/aica-proxy/{**path}", async (HttpContext ctx, string? path) =>
{
    if (string.IsNullOrEmpty(apiKey))
        return Results.Json(new { error = "Proxy not configured" }, statusCode: 503);

    if (string.IsNullOrEmpty(siteOrigin))
        return Results.Json(new { error = "Set AICA:SiteOrigin" }, statusCode: 503);

    var suffix = string.IsNullOrEmpty(path) ? "" : "/" + path.TrimStart('/');
    var allowed = new[] { "", "/session-complete", "/units" };
    if (!allowed.Contains(suffix) && !suffix.StartsWith("/units", StringComparison.Ordinal))
        return Results.Json(new { error = "Not found" }, statusCode: 404);

    var query = ctx.Request.QueryString.HasValue ? ctx.Request.QueryString.Value : "";
    var target = $"{apiBase}{suffix}{query}";

    using var client = new HttpClient();
    var req = new HttpRequestMessage(HttpMethod.Get, target);
    req.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    req.Headers.Add("X-AICA-API-Key", apiKey);
    req.Headers.Add("Origin", siteOrigin);

    if (ctx.Request.Headers.TryGetValue("X-AICA-Session-Id", out var sid))
        req.Headers.Add("X-AICA-Session-Id", sid.ToString());
    if (ctx.Request.Headers.TryGetValue("X-AICA-Interaction-Complete", out var done))
        req.Headers.Add("X-AICA-Interaction-Complete", done.ToString());

    var res = await client.SendAsync(req);
    var body = await res.Content.ReadAsStringAsync();
    return Results.Content(body, "application/json", statusCode: (int)res.StatusCode);
});

app.Run();

Pointer le widget vers votre proxy

<%-- .aspx / Razor: same widget markup --%>
<div id="address-field" data-api-base="/api/aica-proxy"></div>
<script src="https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada/interactive/aica-autocomplete.js"></script>
<script>AicaAutocomplete.mount("#address-field");</script>

cURL / HTTP brut

Appels HTTPS bruts depuis n'importe quel langage. N'intégrez jamais la clé dans le code front-end.

GET style URL (JSON)

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete" \
  --data-urlencode "search=123 main" \
  --data-urlencode "api_key=$AICA_API_KEY"

Alias avec en-tête (widget / proxy / cURL avec X-AICA-API-Key) :

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada" \
  --data-urlencode "search=123 main" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada" \
  --data-urlencode "complex-search=BUILDING_ADDR_ID" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/validate" \
  --data-urlencode "address=24 RUE UINISHK MASHTEUIATSH QC G0W2H0" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/reverse-geocode" \
  --data-urlencode "lat=43.642085" \
  --data-urlencode "lon=-79.374717" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

Points de terminaison

GET

Recherche autocomplete

URL standard qui renvoie du JSON si elle est correctement appelée (clé serveur via ?api_key= ou en-tête) :

GET /v1/address/autocomplete?search={query}&api_key={key}

Alias avec en-tête (widget / proxy / cURL avec X-AICA-API-Key) :

GET /v1/address/autocomplete/canada?search={query}

GET

Unités d'immeuble

Utilisez l'addr_id du bâtiment retourné par l'autocomplétion. Les deux noms de paramètre fonctionnent :

Principal (route autocomplete)

GET /v1/address/autocomplete/canada?complex-search={building_addr_id}

Alias (route units dédiée)

GET /v1/address/autocomplete/canada/units?parent_id={building_addr_id}

GET

Validation d'adresse

Validez une adresse canadienne (style Postes Canada ou partielle) et obtenez la meilleure correspondance officielle avec un score de confiance. Préférez l'auth par en-tête; ?api_key= est réservé à la doc / aux tests.

GET /v1/address/validate?address={address}

URL standard qui renvoie du JSON si elle est correctement appelée (clé serveur via ?api_key= ou en-tête) :

GET /v1/address/validate?address={address}&api_key={key}

Paramètres : address (requis). Accepte les codes postaux avec ou sans espace (G0W 2H0 / G0W2H0), sans virgules, et les types de rue abrégés.

GET

Géocodage inverse

Trouvez l'adresse de bâtiment canadienne la plus proche à partir de la latitude et de la longitude. Les appartements sont exclus — le bâtiment est retourné.

GET /v1/address/reverse-geocode?lat={lat}&lon={lon}

URL standard qui renvoie du JSON si elle est correctement appelée (clé serveur via ?api_key= ou en-tête) :

GET /v1/address/reverse-geocode?lat={lat}&lon={lon}&api_key={key}

Paramètres : lat et lon (requis, pleine précision — ne pas arrondir). Recherche 50 m → 100 m → 250 m. Correspondance exacte = 1 résultat; sinon jusqu'à 3 plus proches.

POST

Fin de session

POST /v1/address/autocomplete/canada/session-complete

Réponses

Pendant la saisie, GET ?search=… renvoie des suggestions :

{
  "results": [{ "id": "f6aefa64-f190-4b67-a1f0-3a2c39303dcb", "label": "1001-1080 BAY ST, TORONTO, ON, M5S 0A5" }],
  "meta": { "count": 1, "search": "1080 bay" }
}

Adresse sélectionnée (widget onSelect)

Quand le visiteur choisit une adresse, votre callback onSelect reçoit l'enregistrement complet (le JSON n'est pas affiché dans l'interface du widget) :

{
  "result": "1001-1080 BAY ST, TORONTO, ON, M5S 0A5",
  "other_meta": {
    "addr_id": "f6aefa64-f190-4b67-a1f0-3a2c39303dcb",
    "is_address_building": false,
    "unit_count": 0,
    "unit": "1001",
    "building_line": "1080 BAY ST",
    "relation_complex": "c45f2597-88a2-4b3d-bfa8-73541f98a845",
    "full_addr": "1001-1080 BAY ST",
    "street_line": "1001-1080 BAY ST",
    "mail_line": "TORONTO ON  M5S 0A5",
    "city": "TORONTO",
    "pruid": 35,
    "postal_code": "M5S 0A5",
    "provice": "Ontario",
    "provice_abbr": "ON",
    "location": {
      "lat": 43.666825,
      "lon": -79.388364
    },
    "display_line": "1001-1080 BAY ST, TORONTO, ON, M5S 0A5"
  }
}

Réponse de validation

Quand la confiance est élevée et qu'une seule adresse domine clairement :

{
  "status": "success",
  "validated": true,
  "confidence": 100,
  "input": "24 RUE UINISHK MASHTEUIATSH QC G0W 2H0",
  "match": {
    "address": "24 RUE UINISHK",
    "city": "MASHTEUIATSH",
    "province": "QC",
    "postal_code": "G0W 2H0",
    "addr_id": "38d303dc-70a1-4b6f-8f2d-3c753cf0490a"
  },
  "alternatives": [
    {
      "address": "1815 RUE NISHK",
      "city": "MASHTEUIATSH",
      "province": "QC",
      "postal_code": "G0W 2H0",
      "addr_id": "cf88d74a-011c-4eda-bba3-0f0092c1509f"
    },
    {
      "address": "1740 RUE NISHK",
      "city": "MASHTEUIATSH",
      "province": "QC",
      "postal_code": "G0W 2H0",
      "addr_id": "b5a0c7bd-a9b3-4d3f-a6aa-b79b5623c83a"
    }
  ]
}

Quand plusieurs adresses ont des scores proches, la validation n'est pas automatique :

{
  "status": "success",
  "validated": false,
  "confidence": 72,
  "input": "24 UINISH",
  "reason": "multiple_matches",
  "choices": [
    {
      "address": "24 RUE UINISHK",
      "city": "MASHTEUIATSH",
      "province": "QC",
      "postal_code": "G0W 2H0",
      "addr_id": "38d303dc-70a1-4b6f-8f2d-3c753cf0490a"
    }
  ]
}

Réponse de géocodage inverse

Les coordonnées ne sont jamais arrondies. Les résultats incluent la distance en mètres et les métadonnées d'unités du bâtiment le cas échéant.

{
  "status": "success",
  "type": "reverse-geocode",
  "query": {
    "lat": 43.642085,
    "lon": -79.374717
  },
  "results": [
    {
      "confidence": 99,
      "distance_meters": 0,
      "address": "1 YONGE ST",
      "city": "TORONTO",
      "province": "ON",
      "postal_code": "M5E 1E5",
      "coordinates": {
        "lat": 43.642085,
        "lon": -79.374717
      },
      "addr_id": "c7073342-4d12-4bfc-9baf-7277310d8c62",
      "building": {
        "has_units": true,
        "unit_count": 22
      }
    }
  ]
}

Erreur

{
  "status": "ok",
  "service": "AICA Address Autocomplete",
  "message": "Hi there, if you are seeing this it means your API request was misconfigured...",
  "documentation": "https://aica-apis.quebecstore.ca/aica-adresse-auto-complete/documentation",
  "instruction": "Use GET /v1/address/autocomplete/canada?search=YOUR_QUERY...",
  "autocomplete": "/v1/address/autocomplete/canada?search=",
  "note": "Service is reachable. See documentation for authentication...",
  "error_reason": "misconfigured api-call",
  "error_code": "AICA-E001"
}

Les routes incorrectes ou mal configurées renvoient un JSON qui inclut l’état du service (status, service, note) ainsi que error_code — pas de page santé séparée.

{
  "error": "The API key is invalid or unknown.",
  "error_reason": "invalid or unknown api-key",
  "error_code": "AICA-E003"
}

Exemples cURL rapides

GET style URL (JSON)

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete" \
  --data-urlencode "search=123 main" \
  --data-urlencode "api_key=$AICA_API_KEY"

https://aica-apis.quebecstore.ca/v1/address/validate?address=24%20RUE%20UINISHK%20MASHTEUIATSH%20QC%20G0W%202H0&api_key=YOUR_API_KEY

https://aica-apis.quebecstore.ca/v1/address/reverse-geocode?lat=43.642085&lon=-79.374717&api_key=YOUR_API_KEY

Alias avec en-tête (widget / proxy / cURL avec X-AICA-API-Key) :

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada" \
  --data-urlencode "search=123 main" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/autocomplete/canada" \
  --data-urlencode "complex-search=BUILDING_ADDR_ID" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/validate" \
  --data-urlencode "address=24 RUE UINISHK MASHTEUIATSH QC G0W2H0" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

-keyword">curl -sG "-url">https://aica-apis.quebecstore.ca/v1/address/reverse-geocode" \
  --data-urlencode "lat=43.642085" \
  --data-urlencode "lon=-79.374717" \
  -H "X-AICA-API-Key: $AICA_API_KEY"

Codes d'erreur

Code	HTTP
AICA-E002	401	Missing API key
AICA-E003	401	Invalid API key
AICA-E004	403	Origin not allowed
AICA-E005	429	Monthly quota exceeded
AICA-E016	429	Rate limit exceeded

Facturation par session

L'utilisation est facturée par session d'interaction, pas par requête HTTP.

Réinitialisation du quota : le 1er de chaque mois à minuit, heure du Québec.

Journaux d'utilisation

Chaque requête API est enregistrée dans votre tableau de bord, sous Utilisation API. Deux champs aident à comprendre ce qui s'est passé :

Recherche — Recherche — ce que l'utilisateur a tapé (ex. h0h 0h0).
Résultats / Réponse — Résultats / Réponse — un résumé court de ce qui a été retourné.

Quand l'utilisateur choisit une adresse finale, le journal affiche une ligne lisible, par ex. PÈRE NOËL, PÔLE NORD, H0H 0H0.

LONG RESPONSE signifie que l'API a retourné plus d'une adresse dans une même réponse. Nous n'enregistrons pas la liste JSON complète — seulement le fait que plusieurs résultats ont été retournés. Cela inclut les immeubles à logements multiples; l'appartement choisi n'apparaît qu'après la sélection de l'unité.

Dans le tableau de bord, les aperçus longs et les lignes LONG RESPONSE affichent un bouton Voir. Cliquez pour ouvrir un panneau centré avec l’aperçu stocké (et une explication pour LONG RESPONSE).

Quand une seule adresse est retournée et que l'utilisateur n'a pas encore terminé, un aperçu sur une ligne peut s'afficher.

Liste blanche d'origines

Restrictions par domaine — AICA-E004.

Forfaits et limites

Forfait	Interactions / mois	Clés API	Domaines	Dépassement
Gratuit	100	1	3	Non
Starter	1,000	5	5	Oui
Pro	3,000	10	10	Oui
Pro Plus	7,000	15	15	Oui
Business	20,000	30	30	Oui
Enterprise	50,000	45	45	Oui

Forfait	/ seconde	/ minute	/ heure
Gratuit	2	60	100
Starter	10	300	1,000
Pro	6	180	3,000
Pro Plus	8	225	7,000
Business	13	400	20,000
Enterprise	17	500	50,000

Quota dépassé → AICA-E005. Limite de débit → AICA-E016 (HTTP 429).

Support

Si votre système utilise nos API et vous rencontrez des problèmes, contactez Quebecstore avant de modifier le code d'intégration.

[email protected] · Contact

Comment voulez-vous intégrer ?

Aperçu

Authentification

Clé en paramètre d’URL (serveur / backend)

Widget intégré

1. Installation en un script (recommandé)

1.A Monter le champ de recherche

2. Installation classique (optionnel — plus d’URLs)

Remplir les champs du formulaire

Langue du widget

Confidentialité du paramètre URL

Dépannage

Backend par stack

Configuration PHP

1. aica-config.php

2. aica-proxy.php

3. Protéger la config (Apache)

4. Pointer le widget vers votre proxy

Configuration Node / Express

1. Installer avec npm

2. Proxy Express

3. Côté serveur uniquement (plus sécurisé)

4. Pointer le widget vers votre proxy

Configuration ASP.NET / ASPX

Pointer le widget vers votre proxy

cURL / HTTP brut

Points de terminaison

Recherche autocomplete

Unités d'immeuble

Validation d'adresse

Géocodage inverse

Fin de session

Réponses

Adresse sélectionnée (widget onSelect)

Réponse de validation

Réponse de géocodage inverse

Erreur

Exemples cURL rapides

Codes d'erreur

Facturation par session

Journaux d'utilisation

Liste blanche d'origines

Forfaits et limites

Support