L'API GNewsalyzer

Présentation

Une API REST, du JSON en entrée comme en sortie, une clé dans un en-tête. Rien d'autre à installer.

Le catalogue des points d'entrée est servi sans clé, pour explorer avant de s'inscrire :

curl https://www.gnewsalyzer.com/api/v2/

Obtenir une clé

Trois étapes, moins d'une minute.

Une clé compromise se révoque depuis la même page : les appels qui l'utilisent reçoivent immédiatement un 401.

Authentification

Envoyez votre clé dans l'en-tête X-API-Key à chaque requête.

curl -H "X-API-Key: gna_votre_cle" \
  "https://www.gnewsalyzer.com/api/v2/me"

<?php
$ch = curl_init('https://www.gnewsalyzer.com/api/v2/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('GNEWSALYZER_API_KEY')],
    CURLOPT_TIMEOUT        => 15,
]);
$reponse = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($reponse['data']);

const reponse = await fetch('https://www.gnewsalyzer.com/api/v2/me', {
  headers: { 'X-API-Key': process.env.GNEWSALYZER_API_KEY }
});

if (!reponse.ok) {
  throw new Error(`API ${reponse.status}`);
}

const { data } = await reponse.json();
console.log(data.quotas);

import os, requests

reponse = requests.get(
    "https://www.gnewsalyzer.com/api/v2/me",
    headers={"X-API-Key": os.environ["GNEWSALYZER_API_KEY"]},
    timeout=15,
)
reponse.raise_for_status()
print(reponse.json()["data"]["quotas"])

Autres formes acceptées

Quotas

Assez larges pour ne jamais gêner un usage normal, assez serrés pour qu'un robot emballé ne mette pas le service à genoux.

Les trois plafonds s'appliquent en même temps et se comptent par compte, pas par clé : émettre plusieurs clés sépare vos environnements, cela ne multiplie pas votre quota. Vous pouvez détenir 5 clés actives.

Coût d'une requête

Une requête vaut une unité, sauf là où le travail demandé dépend de la taille de l'entrée :

En-têtes de réponse

Chaque réponse porte l'état de votre quota, inutile d'appeler /me pour le suivre :

Format des réponses

Toujours la même enveloppe, succès comme échec.

Succès

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-10-17T18:04:11+02:00"
}

Échec

{
  "success": false,
  "error": {
    "message": "Quota dépassé : 60 requêtes par minute au maximum. Réessayez dans 23 secondes.",
    "code": 429
  },
  "timestamp": "2026-10-17T18:04:11+02:00"
}

Pagination

Les listes portent un bloc pagination dans data. Les paramètres page et limit les pilotent ; limit est plafonné à 100.

"pagination": { "total": 128455, "page": 2, "limit": 50, "total_pages": 2570 }

Erreurs

Le code HTTP porte le sens ; le message dit quoi corriger.

Présence dans Discover

Le cœur de l'API : savoir si une URL a été repérée dans Google Discover, et combien de fois.

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/discover/check?url=https://www.20minutes.fr/exemple-article"

{
  "success": true,
  "data": {
    "url": "https://www.20minutes.fr/exemple-article",
    "present": true,
    "occurrences": 3,
    "first_seen": "2026-09-14 06:12:03",
    "last_seen": "2026-09-16 19:40:55",
    "title": "Le titre de l'article",
    "source": "20 Minutes",
    "category": "Actualité"
  },
  "timestamp": "2026-10-17T18:04:11+02:00"
}

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/discover/check?urls=https://a.fr/un,https://b.fr/deux"

{ "urls": ["https://a.fr/un", "https://b.fr/deux"] }

{
  "success": true,
  "data": {
    "summary": { "total": 2, "present": 1, "absent": 1, "truncated": false, "max_urls": 100 },
    "results": [ { "url": "...", "present": true, "occurrences": 2, "...": "..." } ]
  }
}

Articles

Les articles détectés dans Discover, avec leurs métadonnées.

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/articles?limit=20&category=Sport"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/articles/128455"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/articles/search?q=intelligence%20artificielle"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/articles/new?hours=6&limit=50"

Catégories

La classification thématique appliquée aux articles.

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/categories"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/categories/sport/articles?limit=10"

Sujets

Le graphe de sujets construit à partir des articles.

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/topics?sort=recent&limit=20"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/topics/trending?days=7"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/topics/popular"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/topics/search?q=climat"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/topics/6/articles"

Statistiques

Vues agrégées sur l'ensemble du corpus.

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/analytics/overview"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/analytics/categories"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/analytics/trends?days=14"

Votre compte

Vos propres données et l'état de vos quotas.

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/me"

{
  "success": true,
  "data": {
    "cle": { "prefixe": "gna_7f3a9b2c", "nom": "Mon intégration", "compte": 42 },
    "quotas": {
      "minute": { "limite": 60, "utilise": 3, "reste": 57, "reinit": "2026-10-17T16:05:00+00:00" },
      "heure":  { "limite": 1000, "utilise": 148, "reste": 852, "reinit": "..." },
      "jour":   { "limite": 5000, "utilise": 902, "reste": 4098, "reinit": "..." }
    }
  }
}

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/audits"

curl -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/audits/a1b2c3d4e5f6"

Exemples complets

Deux usages courants, à copier tels quels.

Vérifier un lot d'URL après une publication

import os, requests

CLE = os.environ["GNEWSALYZER_API_KEY"]
urls = [
    "https://exemple.fr/article-un",
    "https://exemple.fr/article-deux",
]

reponse = requests.post(
    "https://www.gnewsalyzer.com/api/v2/discover/check",
    headers={"X-API-Key": CLE, "Content-Type": "application/json"},
    json={"urls": urls},
    timeout=30,
)
reponse.raise_for_status()

resultat = reponse.json()["data"]
print(f"{resultat['summary']['present']} / {resultat['summary']['total']} repérées")

for ligne in resultat["results"]:
    etat = f"{ligne['occurrences']}x" if ligne["present"] else "absente"
    print(f"  {etat:>8}  {ligne['url']}")

const CLE = process.env.GNEWSALYZER_API_KEY;

const reponse = await fetch('https://www.gnewsalyzer.com/api/v2/discover/check', {
  method: 'POST',
  headers: { 'X-API-Key': CLE, 'Content-Type': 'application/json' },
  body: JSON.stringify({ urls: [
    'https://exemple.fr/article-un',
    'https://exemple.fr/article-deux',
  ]}),
});

if (reponse.status === 429) {
  const attente = Number(reponse.headers.get('Retry-After') ?? 60);
  throw new Error(`Quota atteint, réessayez dans ${attente} s`);
}

const { data } = await reponse.json();
console.log(`${data.summary.present} / ${data.summary.total} repérées`);

curl -s -X POST "https://www.gnewsalyzer.com/api/v2/discover/check" \
  -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://exemple.fr/un","https://exemple.fr/deux"]}' \
  | jq '.data.summary'

Suivre les articles d'une catégorie

curl -s -H "X-API-Key: $GNEWSALYZER_API_KEY" \
  "https://www.gnewsalyzer.com/api/v2/articles/new?hours=6&limit=50" \
  | jq '.data.articles[] | {titre: .title, source: .source, date: .import_date_iso}'

Spécification OpenAPI

openapi.yaml décrit l'API au format OpenAPI : importez-le dans Postman, Insomnia ou un générateur de client.

Bonnes pratiques

Gardez la clé hors du code

Une variable d'environnement, un gestionnaire de secrets — jamais un dépôt, jamais du JavaScript exécuté dans un navigateur : une clé posée dans une page web est publique. Pour un usage côté navigateur, appelez l'API depuis votre propre serveur.

Traitez le 429 au lieu de le subir

Lisez Retry-After et attendez le délai indiqué. Réessayer immédiatement ne fait que creuser le trou.

for tentative in range(5):
    reponse = requests.get(url, headers=entetes, timeout=15)
    if reponse.status_code != 429:
        break
    time.sleep(int(reponse.headers.get("Retry-After", 60)))

Groupez

Un appel groupé de 100 URL coûte 10 unités ; 100 appels unitaires en coûtent 100. À résultat identique.

Mettez en cache de votre côté

Les données évoluent au rythme des collectes, pas à la seconde. Rafraîchir toutes les quelques minutes suffit largement et vous laisse du quota pour le reste.

Révoquez plutôt que de renommer

Au moindre doute sur une clé — poussée par erreur dans un dépôt, partagée dans un fil de discussion — révoquez-la et créez-en une autre. C'est instantané et gratuit.