{
  "openapi": "3.0.3",
  "info": {
    "title": "Annuaire de l'éducation",
    "version": "2",
    "description": "\nCette API donne accès aux caractéristiques des établissements de l'Éducation nationale : Enseignement, Information et d'Orientation, Établissements administratifs.\n\nL'API est basée sur REST.\n\n- Seule la méthode HTTP `GET` est supportée.\n- Les points d'entrées retournent du JSON.\n- Les points d'entrées utilisent [ODSQL](https://help.opendatasoft.com/apis/ods-search-v2/#odsql). Cela veut dire que les paramètres fonctionnent de la même manière sur l'ensemble des points d'entrées.\n",
    "contact": {}
  },
  "servers": [
    {
      "url": "https://data.education.gouv.fr/api/v2"
    }
  ],
  "security": [
    {
      "api_key": []
    }
  ],
  "tags": [
    {
      "name": "Dataset"
    }
  ],
  "paths": {
    "/catalog/datasets/fr-en-annuaire-education": {
      "get": {
        "tags": [
          "Dataset"
        ],
        "description": "Retourne les métadonnées de l'API et les différents points d'entrées disponibles.\n",
        "operationId": "getDataset",
        "parameters": [
          {
            "$ref": "#/components/parameters/select"
          }
        ],
        "responses": {
          "200": {
            "description": "Annuaire",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/dataset"
                }
              }
            }
          }
        },
        "summary": "Récupérer les métadonnées de l'annuaire",
        "x-internal": false
      },
      "parameters": []
    },
    "/catalog/datasets/fr-en-annuaire-education/records": {
      "get": {
        "tags": [
          "Dataset"
        ],
        "description": "Réalise une requête sur l'annuaire pour récupérer les établissements.\n",
        "operationId": "getRecords",
        "parameters": [
          {
            "$ref": "#/components/parameters/select"
          },
          {
            "$ref": "#/components/parameters/where"
          },
          {
            "$ref": "#/components/parameters/order_by"
          },
          
          {
            "$ref": "#/components/parameters/group_by"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Etablissement",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/record"
                  }
                }
              }
            }
          }
        },
        "summary": "Requêter l'annuaire"
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "dataset": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string"
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {}
            }
          },
          "has_records": {
            "type": "boolean"
          },
          "data_visible": {
            "type": "boolean"
          },
          "features": {
            "type": "array",
            "description": "A map of available features for a dataset, with the fields they apply to.\n",
            "items": {
              "type": "string"
            }
          },
          "metas": {
            "type": "object",
            "properties": {}
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "annotations": {
                  "type": "object",
                  "properties": {}
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "record": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "dateTime"
          },
          "size": {
            "type": "integer"
          },
          "fields": {
            "type": "object",
            "properties": {}
          }
        }
      }
    },
    "parameters": {
      "where": {
        "name": "where",
        "in": "query",
        "description": "Une expression pour filtrer les résultats, qui peut inclure des opérateurs logiques\n(`NOT`, `AND`, `OR`...) ainsi que d'autres fonctions pour effectuer des opérations complexes.\n\nConsultez [la documentation de référence](https://help.opendatasoft.com/apis/ods-search-v2) pour plus de détails.\n\nPar exemple : `statut_public_prive=\"Public\"` pour ne garder que les établissements publics.\n",
        "style": "form",
        "explode": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "description": "Nombre d'établissements à retourner.\n\nA utiliser avec `offset` pour la pagination.\n\nLa valeur maximale de `limit` est 100. Pour récupérer plus de données, vous pouvez utiliser les exports.\nLa valeur par défaut est 10.\n",
        "schema": {
          "maximum": 100,
          "minimum": -1,
          "type": "integer",
          "default": 10
        }
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "description": "Indice du premier établissement à retourner (commence à 0).\n\nA utiliser avec `limit` pour la pagination.\n",
        "schema": {
          "minimum": 0,
          "type": "integer",
          "default": 0
        }
      },
      "select": {
        "name": "select",
        "in": "query",
        "description": "Permet d'ajouter, de supprimer et de modifier les champs retournés.\nUne expression peut être:\n  - un joker `*` : retourne l'ensemble des champs\n  - un nom de champ: retourne seulement ce champ\n  - une expression complexe : retourne le resultat de l'expression. Un label peut être positionné pour cette expression. Par exemple : `count(*) as compte` retournera un nouveau champ nommé `compte` contenant le nombre d'établissements présents dans la requête.\n",
        "schema": {
          "type": "string"
        }
      },
      "group_by": {
        "name": "group_by",
        "in": "query",
        "description": "Permet de grouper les resultats selon les valeurs d'un champ.\n\nPar exemple : `group_by=statut_public_prive` groupe les résultats en fonction du statut de l'établissement.\n",
        "schema": {
          "type": "string"
        }
      },
      "order_by": {
        "name": "order_by",
        "in": "query",
        "description": "Liste de champs séparées par des virgules, suivi par une indication d'ordre (`asc` ou `desc`).\n\nTri les résultats selon les valeurs des champs par ordre croissant par défaut.\nPour trier par ordre décroissant, vous pouvez utiliser le mot clé `desc`.\n\nPar exemple : `nombre_d_eleves desc` pour trier les établissements du plus grand nombre d'élèves au plus petit.\n",
        "style": "form",
        "explode": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "apikey",
        "in": "query"
      }
    }
  }
}