API — Hopctopus

Authentification

Une clé dans un header

Passez votre clé dans le header X-API-Key. Les clés sont fournies à la souscription d'une offre.

curl

curl -H "X-API-Key: $HOPCTOPUS_API_KEY" \
  "https://api.hopctopus.com/api/v1/breweries/?limit=10"

Accès	Authentification	Rate limit
Statistiques publiques (`/stats`)	Aucune	100 req/min
Clients	Clé API (`X-API-Key`)	1 000 req/min
Volumes importants	OAuth2	Sur mesure

Au-delà de la limite, l'API répond 429. Les erreurs renvoient {"detail": "…"} avec le statut 404, 422 ou 500.

Référence

Brasseries

Le dataset unifié (SIRENE + OpenStreetMap, dédoublonné). Réponse paginée : {data, total, limit, offset}.

Endpoint	Description	Paramètres
GET/api/v1/breweries/	Liste des brasseries	city, region, active, brewery_type, activity, postal_code, search, has_website, has_coords, osm_matched, limit (≤ 10000), offset
GET/api/v1/breweries/{brewery_id}	Fiche complète, avec `legal_events` et `osm_data`	—
GET/api/v1/breweries/geo/bounds	Brasseries dans une bounding box	min_lat, max_lat, min_lon, max_lon (requis), limit

curl -H "X-API-Key: $HOPCTOPUS_API_KEY" \
  "https://api.hopctopus.com/api/v1/breweries/?region=Bretagne&active=true&limit=10"

import httpx

client = httpx.Client(
base_url="https://api.hopctopus.com/api/v1",
headers={"X-API-Key": HOPCTOPUS_API_KEY},
)
resp = client.get("/breweries/", params={"region": "Bretagne", "active": True, "limit": 10})
breweries = resp.json()["data"]

const resp = await fetch(
  "https://api.hopctopus.com/api/v1/breweries/?region=Bretagne&active=true&limit=10",
  { headers: { "X-API-Key": HOPCTOPUS_API_KEY } }
);
const { data, total } = await resp.json();

Réponse

{
  "data": [
{
  "brewery_id": "FR-SIRENE-123456789",
  "name": "Brasserie Exemple",
  "siren": "123456789",
  "type": "craft",
  "activity": "brewer",
  "postal_code": "69001",
  "city": "Lyon",
  "region": "Auvergne-Rhône-Alpes",
  "latitude": 45.764,
  "longitude": 4.835,
  "active": true,
  "founded": "2018",
  "website": "https://example.com",
  "osm_matched": true,
  "match_confidence": 0.95
}
  ],
  "total": 5694,
  "limit": 10,
  "offset": 0
}

Événements légaux (BODACC)

Annonces du BODACC rattachées aux brasseries : creation, immatriculation, modification, transfer, receivership, liquidation, closure, accounts_filing.

Endpoint	Description	Paramètres
GET/api/v1/events/	Liste des événements	brewery_id, event_type, region, limit (≤ 10000), offset
GET/api/v1/events/stats	Totaux par type, par année, par région, et par type sur 12 mois	—

curl -H "X-API-Key: $HOPCTOPUS_API_KEY" \
  "https://api.hopctopus.com/api/v1/events/?event_type=receivership&limit=20"

resp = client.get("/events/", params={"event_type": "receivership", "limit": 20})
events = resp.json()["data"]

const resp = await fetch(
  "https://api.hopctopus.com/api/v1/events/?event_type=receivership&limit=20",
  { headers: { "X-API-Key": HOPCTOPUS_API_KEY } }
);
const { data } = await resp.json();

Réponse

{
  "data": [
{
  "event_id": "BODACC-A202600000001",
  "brewery_id": "FR-SIRENE-123456789",
  "siren": "123456789",
  "type": "receivership",
  "family": "Procédures collectives",
  "sub_type": "Jugement d'ouverture",
  "publication_date": "2026-08-11",
  "company_name": "Brasserie Exemple",
  "city": "Lyon",
  "region": "Auvergne-Rhône-Alpes",
  "bodacc_url": "https://www.bodacc.fr/…",
  "tribunal": "Greffe du Tribunal de Commerce de Lyon",
  "matched": true
}
  ],
  "total": 182,
  "limit": 20,
  "offset": 0
}

POIs OpenStreetMap

Points d'intérêt brasseries issus d'OpenStreetMap. Données sous licence ODbL 1.0, livrées séparément avec l'attribution « © contributeurs OpenStreetMap ».

Endpoint	Description	Paramètres
GET/api/v1/osm/	Liste des POIs	category, has_website, has_hours, limit (≤ 10000), offset
GET/api/v1/osm/stats	Complétude des POIs (coordonnées, site, horaires, téléphone)	—

curl -H "X-API-Key: $HOPCTOPUS_API_KEY" \
  "https://api.hopctopus.com/api/v1/osm/?has_hours=true&limit=50"

resp = client.get("/osm/", params={"has_hours": True, "limit": 50})
pois = resp.json()["data"]

const resp = await fetch(
  "https://api.hopctopus.com/api/v1/osm/?has_hours=true&limit=50",
  { headers: { "X-API-Key": HOPCTOPUS_API_KEY } }
);
const { data, license } = await resp.json();

Réponse

{
  "data": [
{
  "osm_poi_id": "OSM-node-1000000",
  "name": "Micro Brasserie de Chamonix",
  "latitude": 45.9234,
  "longitude": 6.869,
  "osm_category": "craft=brewery",
  "osm_website": "https://example.com",
  "osm_opening_hours": "Mo-Fr 10:00-18:00",
  "osm_address_city": "Chamonix",
  "osm_address_postcode": "74400"
}
  ],
  "total": 387,
  "limit": 50,
  "offset": 0,
  "license": "ODbL 1.0 — OpenStreetMap contributors"
}

Statistiques

Les agrégats affichés sur la page d'accueil.

Endpoint	Description	Paramètres
GET/api/v1/stats/	Chiffres clés et date de mise à jour	—
GET/api/v1/stats/breweries/by-region	Brasseries par région	limit (défaut 20)
GET/api/v1/stats/breweries/by-city	Brasseries par ville	limit (défaut 20)
GET/api/v1/stats/breweries/by-type	Brasseries par type	—
GET/api/v1/stats/breweries/new	Créations récentes : compteur glissant et créations par mois	days (défaut 30), months (défaut 12)

curl "https://api.hopctopus.com/api/v1/stats/"

stats = client.get("/stats/").json()
print(stats["breweries_active"], "brasseries actives")

const stats = await fetch("https://api.hopctopus.com/api/v1/stats/")
  .then((r) => r.json());

Réponse

{
  "breweries": 5694,
  "breweries_active": 4181,
  "breweries_geocoded": 5239,
  "breweries_by_source": { "sirene": 4603, "osm": 1091 },
  "legal_events": 17011,
  "osm_pois": 1137,
  "beers": 0,
  "venues": 0,
  "updated_at": "2026-10-06"
}

Bières

Catalogue des références. Collecte en cours : les endpoints renvoient une liste vide pour l'instant.

Endpoint	Description	Paramètres
GET/api/v1/beers/	Liste des bières	brewery_id, style, abv_min, abv_max, limit (≤ 500), offset
GET/api/v1/beers/{beer_id}	Détail d'une bière	—

curl

curl -H "X-API-Key: $HOPCTOPUS_API_KEY" \
  "https://api.hopctopus.com/api/v1/beers/?style=IPA&abv_min=5"

Réponse

{ "data": [], "total": 0, "limit": 50, "offset": 0 }

Points de vente

Bars, caves et grandes surfaces. Collecte en cours : les endpoints renvoient une liste vide pour l'instant.

Endpoint	Description	Paramètres
GET/api/v1/venues/	Liste des points de vente	city, venue_type, limit (≤ 500), offset
GET/api/v1/venues/{venue_id}	Détail d'un point de vente	—

curl

curl -H "X-API-Key: $HOPCTOPUS_API_KEY" \
  "https://api.hopctopus.com/api/v1/venues/?city=Lyon&venue_type=bar"

Réponse

{ "data": [], "total": 0, "limit": 50, "offset": 0 }

Public (déprécié)

Endpoints sans clé de l'ancien site vitrine, limités à la France. Ce site ne les utilise plus : ils seront retirés à la prochaine version. Ils ne renvoient ni identifiant, ni SIREN, ni adresse. Réponses en cache une heure.

Endpoint	Description	Paramètres
GET/api/v1/public/map	Brasseries actives géolocalisées : `name`, `city`, `lat`, `lon` (arrondis à 3 décimales)	—
GET/api/v1/public/example	Une fiche réelle, champs sensibles masqués	—

curl

curl "https://api.hopctopus.com/api/v1/public/map"

Réponse

[
  { "name": "Brasserie Exemple", "city": "Lyon", "lat": 45.764, "lon": 4.835 }
]

Système

Endpoint	Description	Paramètres
GET/health	État du service et version	—

curl

curl "https://api.hopctopus.com/health"

Réponse

{ "status": "ok", "version": "0.1.0" }

Demander une clé API Ouvrir le Swagger

Toutes les brasseries, en JSON.

Une clé dans un header

Endpoints

Brasseries

Événements légaux (BODACC)

POIs OpenStreetMap

Statistiques

Bières

Points de vente

Public (déprécié)

Système