API Documentation - BlacklistIP

Introduction

Cette API JSON donne accès à la base d’IP malveillantes, aux statistiques et aux fichiers téléchargeables. Toutes les réponses respectent le format :

{
  "ok": true,
  "meta": { ... },
  "data": [ ... ] | { ... }
}

Authentification

Envoyez votre clé dans le header X-API-Key.

GET https://blacklistip.com/api/v1/bans
X-API-Key: <votre_clé>

Sans clé valide : 401 Unauthorized.

Rate limiting

Limite configurable (ex. 60 requêtes / minute) appliquée par clé, ou par IP si clé absente.

Sur quota dépassé : 429 Too Many Requests avec Retry-After.
Headers utiles : RateLimit-Remaining, RateLimit-Reset.

Endpoints

GET /api/v1

Infos API et liste des endpoints.

curl -H "X-API-Key: <clé>" "https://blacklistip.com/api/v1"

GET /api/v1/bans

Liste paginée des IP bannies avec filtres.

Param	Type	Description	Exemple
ip	string	IP exacte	1.2.3.4
country	string	Pays (code/nom selon données)	FR
fai	string	Fournisseur d’accès	Orange
action	string	Niveau/Action (ex. BLOCK)	BLOCK
port	int	Port associé	22
dateFrom	string	ISO ou relatif	2025-01-01
dateTo	string	ISO ou relatif	2025-01-31
page	int	Page (≥ 1)	1
limit	int	Items/page (≤ 500)	50
sort	string	date_desc (défaut), date_asc, ip_asc, ip_desc	date_desc

curl -G "https://blacklistip.com/api/v1/bans" \
  -H "X-API-Key: <clé>" \
  --data-urlencode "country=FR" \
  --data-urlencode "port=22" \
  --data-urlencode "dateFrom=2025-01-01" \
  --data-urlencode "limit=50"

{
  "ok": true,
  "meta": {
    "page": 1, "limit": 50, "total": 123456, "count": 50,
    "sort": "date_desc",
    "filters": {"country":"FR","port":22,"dateFrom":"2025-01-01"}
  },
  "data": [
    {
      "id": 987654,
      "ip": "1.2.3.4",
      "port": 22,
      "country": "FR",
      "fai": "Orange",
      "action": "BLOCK",
      "date": "2025-08-01T12:34:56+00:00"
    }
  ]
}

GET /api/v1/bans/{ip}

Historique max 100 entrées pour une IP.

curl -H "X-API-Key: <clé>" "https://blacklistip.com/api/v1/bans/1.2.3.4"

GET /api/v1/stats/summary

Chiffres clés + top pays/FAI.

{
  "ok": true,
  "data": {
    "totalIPs": 123456,
    "totalCountries": 127,
    "totalFAIs": 842,
    "last24h": 321,
    "topCountries": [{"country":"US","number":12345}, ...],
    "topFAIs": [{"fai":"AS123","number":9999}, ...],
    "generatedAt":"2025-08-24T17:00:00+00:00"
  }
}

GET /api/v1/files

Liste des fichiers téléchargeables. Filtrer par année/mois.

Param	Type	Description	Exemple
year	int	Année	2025
month	int	Mois 1-12	8

curl -H "X-API-Key: <clé>" "https://blacklistip.com/api/v1/files?year=2025&month=8"

{
  "ok": true,
  "meta": { "year": 2025, "month": 8, "count": 31 },
  "data": [
    {
      "filename": "blacklistip-2025-08-01.json",
      "extension": "json",
      "sizeBytes": 1234567,
      "sizeHuman": "1.18 MB",
      "mtime": "2025-08-01T23:00:05+00:00",
      "year": 2025,
      "month": 8,
      "url": "https://blacklistip.com/downloads/2025/08/blacklistip-2025-08-01.json"
    }
  ]
}

Erreurs

Code	Cause	Corps
400	Paramètre invalide	{"ok":false,"error":{"message":"..."}}
401	Clé absente/invalide	{"ok":false,"error":{"message":"Unauthorized: invalid API key"}}
404	Ressource introuvable	{"ok":false,"error":{"message":"..."}}
429	Quota dépassé	{"ok":false,"error":{"message":"Too Many Requests","retryAfterSeconds":12}}
500	Erreur serveur	{"ok":false,"error":{"message":"..."}}

Exemples

cURL

curl -G "https://blacklistip.com/api/v1/bans" \
  -H "X-API-Key: <clé>" \
  --data-urlencode "country=FR" \
  --data-urlencode "limit=10"

JavaScript (fetch)

const resp = await fetch('https://blacklistip.com/api/v1/bans?limit=10', {
  headers: { 'X-API-Key': 'VOTRE_CLE' }
});
const json = await resp.json();
console.log(json);

Python (requests)

import requests
r = requests.get('https://blacklistip.com/api/v1/bans', headers={'X-API-Key':'VOTRE_CLE'}, params={'limit': 10})
print(r.json())