Pagination et filtrage

Parcourir les collections avec limit, offset et since.

Les collections — /v1/companies et /v1/leads — renvoient toutes la même enveloppe :

{
  "total": 137,
  "limit": 50,
  "offset": 0,
  "data": [ /* … */ ]
}

Champ	Signification
total	Nombre d’éléments correspondant au filtre, toutes pages confondues
limit	Taille de page effectivement appliquée
offset	Position de la page dans le jeu de résultats
data	Les éléments de la page

​

Paramètres

limit · integer · défaut: "50"

Nombre d’éléments par page. Minimum 1, maximum 200. Une valeur hors bornes est rejetée par un 400, elle n’est pas silencieusement ramenée dans l’intervalle.

offset · integer · défaut: "0"

Nombre d’éléments à ignorer avant le début de la page.

since · string

Date ISO 8601. Ne renvoie que les éléments postérieurs.

Le champ filtré dépend de la collection : date de dernière visite (lastSeen) pour les entreprises, date de création (createdAt) pour les leads.

​

Ordre de tri

Les deux collections sont triées par score d’intention décroissant, et cet ordre n’est pas configurable. La première page est donc celle des comptes les plus chauds.

Ce tri a une conséquence sur la pagination : le score d’intention évolue au fil des visites. Entre la lecture de la page 1 et celle de la page 4, une entreprise peut avoir changé de rang, être vue deux fois, ou ne pas être vue du tout.

Pour un export exhaustif, paginez rapidement, et utilisez total pour vérifier votre compte final. Pour une synchronisation régulière, préférez since, qui ne dépend pas du rang.

​

Parcourir toutes les pages

const KEY = process.env.SPOTTRACKER_API_KEY;
const LIMIT = 200;

async function toutesLesEntreprises() {
  const out = [];
  let offset = 0;

  for (;;) {
    const url = `https://api.spottracker.fr/v1/companies?limit=${LIMIT}&offset=${offset}`;
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

    const page = await res.json();
    out.push(...page.data);

    // On s'arrête sur une page incomplète plutôt que sur `total` : `total` est
    // recalculé à chaque appel et peut bouger pendant la pagination.
    if (page.data.length < LIMIT) return out;
    offset += LIMIT;
  }
}

À 200 éléments par page et 120 requêtes par minute, vous lisez 24 000 entreprises par minute. Il n’y a pratiquement jamais de raison de descendre la taille de page pour « ménager » l’API : c’est le nombre de requêtes qui est limité, pas le volume.

​

Synchronisation incrémentale

// Date du dernier passage réussi, prise AVANT la lecture.
const depuis = await lireDerniereSynchro();
const debutDeCePassage = new Date().toISOString();

const url = `https://api.spottracker.fr/v1/companies?since=${depuis}&limit=200`;
// … pagination identique …

await enregistrerDerniereSynchro(debutDeCePassage);

Prendre l’horodatage avant la lecture, et non après, évite de manquer les visites survenues pendant la pagination. Le prix à payer est un léger recouvrement d’un passage à l’autre : traitez les éléments par id, de manière idempotente.