Répartition géographique

Chaque fois qu'un destinataire télécharge un fichier que vous avez partagé, Coffrify enregistre le pays et, lorsque c'est connu, la ville d'origine de l'accès. L'endpoint GET /v1/analytics/geo agrège ces enregistrements et vous renvoie une répartition par pays et par ville sur la période de votre choix. Vous l'utilisez pour deux choses : comprendre votre audience (d'où viennent réellement vos téléchargements) et repérer un accès anormal (un document destiné à un client français ouvert depuis une région inattendue, par exemple).

L'appel s'authentifie comme tout le reste de l'API, avec votre clé secrète dans l'en-tête Authorization: Bearer <clé>. La clé doit porter le scope analytics:read, faute de quoi la réponse est une erreur scope_missing. C'est une lecture seule : aucune écriture, donc pas d'en-tête Idempotency-Key à fournir.

Paramètres

Un seul paramètre de requête est accepté. Il définit la fenêtre temporelle sur laquelle les téléchargements sont agrégés.

Exemple de requête

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const geo = await coffrify.analytics.geoBreakdown({ range_days: 30 });
 
for (const pays of geo.by_country) {
  console.log(`${pays.country_name} (${pays.country_code}) : ${pays.count} téléchargements`);
}

Forme de la réponse

La réponse renvoie la fenêtre effectivement appliquée puis deux listes triées : by_country (tous les pays observés, du plus actif au moins actif) et by_city (les villes, même tri, limitées aux 50 premières). Le champ count est, dans les deux cas, le nombre de téléchargements comptabilisés sur la période. Quand la ville ou le pays d'un accès n'a pas pu être déterminé, cet accès n'apparaît simplement pas dans la liste correspondante.

{
  "range_days": 30,
  "by_country": [
    { "country_code": "FR", "country_name": "France", "count": 1240 },
    { "country_code": "DE", "country_name": "Allemagne", "count": 318 },
    { "country_code": "BE", "country_name": "Belgique", "count": 142 }
  ],
  "by_city": [
    { "city": "Paris", "country_code": "FR", "count": 540 },
    { "city": "Lyon", "country_code": "FR", "count": 188 },
    { "city": "Berlin", "country_code": "DE", "count": 121 }
  ]
}

Cas d'usage : comprendre son audience

Pour un tableau de bord ou un rapport mensuel, by_country vous donne directement la carte de votre audience. Vous pouvez par exemple ne garder que les pays au-dessus d'un certain volume, ou calculer la part de chaque pays dans le total. Élargissez la fenêtre pour lisser les variations hebdomadaires.

const geo = await coffrify.analytics.geoBreakdown({ range_days: 90 });
 
const total = geo.by_country.reduce((s, p) => s + p.count, 0);
const top5 = geo.by_country.slice(0, 5).map((p) => ({
  pays: p.country_name,
  part: total ? Math.round((p.count / total) * 100) : 0,
}));
 
console.table(top5);

Cas d'usage : détecter un accès anormal

Si vos documents s'adressent à un public connu, par exemple uniquement en France et dans l'UE, tout pays inattendu dans by_country mérite un coup d'œil. Une vérification simple consiste à comparer les codes pays observés à votre liste de pays autorisés et à signaler les autres.

const attendus = new Set(['FR', 'BE', 'CH', 'DE', 'ES', 'IT']);
const geo = await coffrify.analytics.geoBreakdown({ range_days: 7 });
 
const inattendus = geo.by_country.filter((p) => !attendus.has(p.country_code));
if (inattendus.length) {
  console.warn('Téléchargements depuis des pays inattendus :', inattendus);
}

Limitation de débit et erreurs

Comme tous les endpoints, celui-ci est soumis à la limitation de débit : surveillez les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset, et respectez Retry-After en cas de réponse 429. Les erreurs suivent le format standard {"error":{"code","message","request_id"}} ; les codes les plus probables ici sont invalid_api_key (clé absente ou invalide) et scope_missing (la clé n'a pas analytics:read). Conservez request_id si vous devez nous contacter au sujet d'une réponse.