API et données ouvertes

Cinq adresses

• /api/address?q={adresse}

  Une adresse en toutes lettres donne ses établissements de secteur, de la maternelle au lycée, et dit ce qui fait foi : la carte publiée, la seule école publique de la commune, ou un secteur non publié. La réponse ajoute les établissements publics les plus proches, les formations Parcoursup voisines et le privé sous contrat.

  Essayer : https://lesbancs.fr/api/address?q=60%20rue%20Pasteur%2C%20Vitry-sur-Seine

• /api/school/{uai}

  Un UAI donne la fiche entière d'un établissement : effectifs, IPS, résultats au brevet et au bac sur quatre sessions à côté des moyennes du département et de la France, note sur 10 et rangs, particularités, formations Parcoursup et communes de son secteur.

  Essayer : https://lesbancs.fr/api/school/0942434K

• /api/commune/{insee}

  Un code INSEE donne les établissements de la commune, niveau par niveau, et dit si sa carte scolaire des collèges et des lycées est publiée. Paris, Lyon et Marseille comptent leurs arrondissements.

  Essayer : https://lesbancs.fr/api/commune/49007

• /api/ranking/{type}?dep=&insee=&sector=&sort=&criteria=

  Le classement des collèges, des lycées ou des lycées professionnels de France, d'un département ou d'une ville, par note sur 10, taux de réussite ou valeur ajoutée. Une page compte 1 000 lignes par défaut et 12 000 au plus, avec limit et offset.

  Essayer : https://lesbancs.fr/api/ranking/colleges?dep=49

• /api/sectors/{dep}/{level}

  Les secteurs dessinés d'un département en GeoJSON, un fichier par niveau : collèges (middle-school), lycées (high-school), écoles élémentaires (primary-school) et maternelles (nursery-school).

  Essayer : https://lesbancs.fr/api/sectors/49/middle-school

Le contrat OpenAPI 3.1, généré depuis le code qui sert ces adresses : https://lesbancs.fr/api/openapi.json. Chaque réponse donne un en-tête Link vers ce contrat et vers cette page.

Les règles d'une réponse

• Aucun secteur n'est deviné. Pour chaque niveau, sector_basis dit ce qui fait foi : la carte scolaire publiée, par la voie ou par la commune, ou la seule école publique de la commune. Il vaut null quand le secteur n'est pas publié, et la réponse donne alors les établissements les plus proches.
• null veut dire « la source ne le dit pas », jamais une chaîne vide ni un zéro. Aucune note n'existe pour une école primaire : aucun résultat public n'existe par école.
• La même enveloppe sur chaque succès : source, served_by, terms, documentation, notice. Ces noms sont réservés.
• Toute adresse est absolue.url mène à la page du site, api_url à la même chose en JSON.
• Un classement arrive par pages : le bloc page donne le total et les adresses absolues de la page suivante et de la précédente, les mêmes en en-tête Link. Un paramètre illisible retombe sur le défaut, jamais sur un refus.

La promesse

• Additive, sans numéro de version. Un champ peut apparaître ; aucun ne disparaît ni ne change de sens sous un appelant, et une adresse ne bouge pas.
• Un ETag faible sur chaque réponse, If-None-Match honoré, 304 vide. Chaque réponse reste une journée en cache, comme les pages.
• CORS ouvert, etag et link exposés.
• Aucune borne de débit. Le site lit une base D1 et garde chaque réponse une journée en cache : une aspiration ne coûte qu'un rendu par adresse, et rien n'est à protéger.
• Hors index (x-robots-tag: noindex) : un programme lit ces adresses, les moteurs de recherche trouvent cette page.

14 refus

Tout refus est un application/problem+json (RFC 9457), sans enveloppe et no-store. Son champ type mène à l'une de ces ancres, instance donne le chemin demandé et received ce qui a été lu.

invalid-query 400

Le paramètre q manque, ou compte moins de trois signes.

address-not-found 404

La Base Adresse Nationale ne trouve aucune adresse assez sûre. Précisez la commune ou le code postal.

geocoder-unavailable 503

La Base Adresse Nationale ne répond pas. Cela ne dit rien de l'adresse : réessayez après les secondes de retry-after.

invalid-uai 400

L'UAI n'a pas sa forme : sept chiffres et une lettre, par exemple 0942434K.

school-not-found 404

Aucun établissement ouvert n'a cet UAI dans l'annuaire de l'éducation.

invalid-insee-code 400

Le code INSEE ne compte pas cinq caractères (2A et 2B en Corse). Un code postal n'est pas un code INSEE.

municipality-not-found 404

Aucune commune n'a ce code INSEE.

ranking-not-found 404

Ce classement n'existe pas. Les trois classements sont colleges, lycees et lycees-professionnels.

invalid-department 400

Ce département n'existe pas. Un code compte deux caractères de 01 à 95, 2A ou 2B en Corse, trois outre-mer.

invalid-level 400

Ce niveau n'existe pas. Les quatre niveaux sont middle-school, high-school, primary-school et nursery-school.

sectors-not-published 404

Aucun secteur de ce niveau n'est dessiné dans ce département.

database-unavailable 503

La base ne répond pas. Cela ne dit rien de ce qui est demandé : réessayez après les secondes de retry-after.

method-not-allowed 405

La méthode n'est ni GET, ni HEAD, ni OPTIONS. La réponse donne l'en-tête Allow.

not-found 404

Aucune adresse de l'API n'existe à ce chemin.

Les autres formes des mêmes faits

• Le serveur MCP, à https://lesbancs.fr/mcp (et /api/mcp) : sans état, en POST seulement, révisions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. Ses 4 outils répondent en texte, à partir des mêmes lectures que l'API : get_french_school_sectors, get_french_school, get_french_commune_schools, get_french_school_ranking. Il est déclaré à l'annuaire officiel sous le nom fr.lesbancs/lesbancs.
• Le contrat OpenAPI, à https://lesbancs.fr/api/openapi.json, pour générer un client.

Citer

Ministère de l'Éducation nationale, région académique Occitanie et académies, communes, ministère de l'Enseignement supérieur (Parcoursup) et Base Adresse Nationale, sous Licence Ouverte 2.0 (Etalab) ; particularités de l'ONISEP sous Open Database License (ODbL). La réutilisation est libre, en citant la source : le champ source de chaque réponse donne la phrase à recopier.