openapi: "3.1.0"
info:
  title: API Géoplateforme - Géocodage
  description: Ce service permet d'obtenir des coordonnées à partir d'une adresse ou d'un nom de lieu / point d'intérêt ou d'une parcelle (ou l'inverse...).
  contact:
      name: "Geoplateforme"
      email: "geoplateforme@ign.fr"
      url: "http://cartes.gouv.fr"
  version: 1.0.0
  termsOfService: "https://cartes.gouv.fr/cgu"
  license:
    name: Licence ouverte 2.0
    url: https://www.etalab.gouv.fr/licence-ouverte-open-licence
servers:
  - url: https://data.geopf.fr/geocodage
tags:
  - name: getCapabilities
    description: Découverte du service
  - name: search
    description: Géocodage direct (recherche)
  - name: reverse
    description: Géocodage inverse
  - name: batch
    description: Géocodage par lot synchrone
  - name: batch-async
    description: Géocodage par lot asynchrone
paths:
  /getCapabilities:
    get:
      tags:
        - getCapabilities
      summary: Découvrir le service
      description: "Découvrir le service: les opérations possibles, les ressources disponibles et les options proposées."
      operationId: getCapabilities
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Getcapabilities"
        404:
          description: Not found

  /search:
    get:
      tags:
        - search
      summary: Recherche par géocodage direct
      operationId: search
      parameters:
        - name: q
          in: query
          description: |
            chaîne décrivant la localisation à rechercher

            Exemples de requêtes:
            - /search?q=73 Avenue de Paris Saint-Mandé
            - /search?q=cimetière Vincennes
            - /search?q=75056104AE0003

            Note:
            L'absence de valeur est autorisée sur le type parcel pour réaliser une recherche structurée.
            Par exemple: /search?q=&index=parcel&departmentcode=75&municipalitycode=056&section=AV
          required: false
          schema:
            type: string
        - name: autocomplete
          in: query
          description: |
            indique si la recherche doit être effectuée en mode auto-complétion (comportement par défaut).
          schema:
            type: string
            enum: ["1", "0"]
            default: "1"
        - name: index
          in: query
          description: |
            index(es) de recherche :
            - <b>address</b> pour la recherche par adresse
            - <b>parcel</b> pour la recherche par parcelle cadastrale
            - <b>poi</b> pour la recherche par lieu et unité administrative

            Il est possible de spécifier plusieurs indexes séparés par une virgule.

            Exemples:
            - /search?index=parcel
            - /search?index=poi,address
          required: false
          schema:
            $ref: "#/components/schemas/Index"
        - name: limit
          in: query
          description: |
            Nombre maximum de résultats retournés.
            La valeur ne peut pas dépasser 50.
            Dans le cas où returntruegeometry est activé, la valeur est automatiquement ramenée à 20.
          schema:
            type: integer
            default: 10
        - name: lat
          in: query
          description: "latitude d'un localisant pour favoriser les candidats les plus proches."
          schema:
            type: number
        - name: lon
          in: query
          description: "longitude d'un localisant pour favoriser les candidats les plus proches."
          schema:
            type: number
        - name: returntruegeometry
          in: query
          description: "indique si la vraie géométrie doit être retournée"
          schema:
            type: boolean
            default: false
        - name: postcode
          in: query
          description: "Filtre pour les index address et poi. Il permet de filtrer les résultats par code postal. Accepte plusieurs valeurs séparées par des virgules (maximum 50)."
          schema:
            oneOf:
              - $ref: "#/components/schemas/PostalCode"
              - type: array
                items:
                  $ref: "#/components/schemas/PostalCode"
                maxItems: 50
          style: form
          explode: false
        - name: citycode
          in: query
          description: "Filtre pour les index address et poi. Il permet de filtrer les résultats par code INSEE. Accepte plusieurs valeurs séparées par des virgules (maximum 200)."
          schema:
            oneOf:
              - $ref: "#/components/schemas/InseeCode"
              - type: array
                items:
                  $ref: "#/components/schemas/InseeCode"
                maxItems: 200
          style: form
          explode: false
        - name: depcode
          in: query
          description: "Filtre pour les index address et poi. Il permet de filtrer les résultats par code départmeent. Accepte plusieurs valeurs séparées par des virgules (maximum 10)."
          schema:
            oneOf:
              - $ref: "#/components/schemas/DepCode"
              - type: array
                items:
                  $ref: "#/components/schemas/DepCode"
                maxItems: 10
          style: form
          explode: false
        - name: type
          in: query
          description: "Filtre pour l'index address. Il permet de filtrer par type de données adresse : numéro de maison, rue, commune, ..."
          schema:
            type: string
            enum: ["housenumber", "street", "locality", "municipality"]
        - name: city
          in: query
          description: "Filtre pour les index address et poi. Il permet de filtrer par nom de commune."
          schema:
            type: string
        - name: category
          in: query
          description: |
            Filtre pour l'index poi. Il permet de filtrer par catégorie de poi.
            Les valeurs possibles sont listées dans le getCapabilities du service de géocodage.
            Accepte plusieurs valeurs séparées par des virgules (maximum 10).
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
                maxItems: 10
          style: form
          explode: false
        - name: departmentcode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code de département."
          schema:
            type: string
        - name: municipalitycode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code de commune."
          schema:
            type: string
        - name: oldmunicipalitycode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code d'ancienne commune."
          schema:
            type: string
        - name: districtcode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code d'arrondissement."
          schema:
            type: string
        - name: section
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par section."
          schema:
            type: string
        - name: number
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par numéro."
          schema:
            type: string
        - name: sheet
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par feuille."
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      $ref: "#/components/schemas/GeocodeResponse"
        "400":
          description: "Parse query failed"
          content:
            application/json: {}
  /reverse:
    get:
      tags:
        - reverse
      summary: Recherche par géocodage inverse
      operationId: reverse
      parameters:
        - name: searchgeom
          in: query
          required: false
          description: |
            Géométrie de recherche. La géométrie est réalisé par intersection géométrique. Si ce paramètre est utilisé seul, c''est que l''on souhaite une recherche sans ordonnancement des résultats (tous les objets intersectant la géométrie de recherche ont un score de 1).
            Si on veut ordonner les résultats, on peut alors utiliser les paramètres lon et lat pour préciser un point d''ordonnancement.
            Ce paramètre n''est pas obligatoire pour des raisons de rétro-compatibilité. Si searchgeom n''est pas utilisé alors les paramètres lon et lat doivent l''être et on parle de point de recherche.
            Lorsque la recherche est réalisée par intersection géométrique. Les types géométrique autorisés sont :

            - Point

            - LineString

            - Polygon

            - Circle
            Exemple de géométrie de type Circle :
            {
            &nbsp;&nbsp;&nbsp;&nbsp;"type": "Circle",
            &nbsp;&nbsp;&nbsp;&nbsp;"coordinates": [2.294469, 48.858244],
            &nbsp;&nbsp;&nbsp;&nbsp;"radius": 100
            }
            Pour l''index <b>address</b>, seules les géométries de type ''Polygon'' et ''Circle'' sont autorisées.
            Le plus grand côté du rectangle d’emprise de la géométrie ne doit pas excéder 1000 mètres.
          schema:
            type: string
        - name: lon
          in: query
          description: |
            Si searchgeom est utilisé, il s'agit de la longitude du point d'ordonnancement. C'est le point à partir duquel est calculée la distance, puis le score permettant l'ordonnancement des résultats.
            Dans un soucis de rétro-compatibilité, si searchgeom n'est pas utilisé, il s'agit de la longitude du point de recherche. À partir de ce point, un cercle est créé pour effectuer la recherche. En plus, ce sera aussi la longitude du point d'ordonnancement.
          required: false
          schema:
            type: number
        - name: lat
          in: query
          description: |
            Si searchgeom est utilisé, il s'agit de la latitude  du point d'ordonnancement. C'est le point à partir duquel est calculée la distance, puis le score permettant l'ordonnancement des résultats.
            Dans un soucis de rétro-compatibilité, si searchgeom n'est pas utilisé, il s'agit de la latitude du point de recherche. À partir de ce point, un cercle est créé pour effectuer la recherche. En plus, ce sera aussi la latitude du point d'ordonnancement.
          required: false
          schema:
            type: number
        - name: index
          in: query
          description: |
            index de recherche :
            - <b>address</b> pour la recherche par adresse
            - <b>parcel</b> pour la recherche par parcelle cadastrale
            - <b>poi</b> pour la recherche par lieu et unité administrative

            Il est possible de spécifier plusieurs indexes séparés par une virgule.

            Exemples:
            - /search?index=parcel
            - /search?index=poi,address
          required: false
          schema:
            $ref: "#/components/schemas/Index"
        - name: limit
          in: query
          description: |
            Nombre maximum de résultats retournés.
            La valeur ne peut pas dépasser 50.
            Dans le cas où returntruegeometry est activé, la valeur est automatiquement ramenée à 20.
          schema:
            type: integer
            default: 10
        - name: returntruegeometry
          in: query
          description: "indique si la vraie géométrie doit être retournée"
          schema:
            type: boolean
            default: False
        - name: postcode
          in: query
          description: "Filtre pour les index address et poi. Il permet de filtrer les résultats par code postal. Accepte plusieurs valeurs séparées par des virgules (maximum 50)."
          schema:
            oneOf:
              - $ref: "#/components/schemas/PostalCode"
              - type: array
                items:
                  $ref: "#/components/schemas/PostalCode"
                maxItems: 50
          style: form
          explode: false
        - name: citycode
          in: query
          description: "Filtre pour les index address et poi. Il permet de filtrer les résultats par code INSEE. Accepte plusieurs valeurs séparées par des virgules (maximum 50)."
          schema:
            oneOf:
              - $ref: "#/components/schemas/InseeCode"
              - type: array
                items:
                  $ref: "#/components/schemas/InseeCode"
                maxItems: 50
          style: form
          explode: false
        - name: type
          in: query
          description: "Filtre pour l'index address. Il permet de filtrer par type de données adresse : numéro de maison, rue, commune, ..."
          schema:
            type: string
            enum: ["housenumber", "street", "locality", "municipality"]
        - name: city
          in: query
          description: "Filtre pour les index address et parcel. Il permet de filtrer par nom de commune."
          schema:
            type: string
        - name: category
          in: query
          description: |
            Filtre pour l'index poi. Il permet de filtrer par catégorie de poi.
            Les valeurs possibles sont listées dans le getCapabilities du service de géocodage.
            Accepte plusieurs valeurs séparées par des virgules (maximum 10).
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
                maxItems: 10
          style: form
          explode: false
        - name: departmentcode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code de département."
          schema:
            type: string
        - name: municipalitycode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code de commune."
          schema:
            type: string
        - name: oldmunicipalitycode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code d'ancienne commune."
          schema:
            type: string
        - name: districtcode
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par code d'arrondissement."
          schema:
            type: string
        - name: section
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par section."
          schema:
            type: string
        - name: number
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par numéro."
          schema:
            type: string
        - name: sheet
          in: query
          description: "Filtre pour l'index parcel. Il permet de filtrer par feuille."
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      $ref: "#/components/schemas/GeocodeReverseResponse"
        "400":
          description: "Parse query failed"
          content:
            application/json: {}

  /search/csv:
    post:
      tags:
        - search
        - batch
      summary: Géocodage direct en masse d’un fichier CSV
      description: |
        Géocodage direct en masse d’un fichier CSV. Les paramètres de la requête permettent de spécifier les colonnes à utiliser pour le géocodage, les index à utiliser, les filtres à appliquer et les colonnes à conserver dans le fichier CSV de sortie.

        Le fichier soumis doit faire une taille maximale de 50 Mo.
      operationId: searchCsv
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: string
                  format: binary
                  description: "Fichier CSV contenant les lignes à géocoder"
                columns:
                  type: array
                  items:
                    type: string
                  description: |
                    Liste des colonnes du fichier CSV à utiliser pour le géocodage. Celles-ci seront concaténées pour former le critère de recherche texte.

                    Si le paramètre n'est pas fourni toutes les colonnes seront concaténées, ce qui est rarement souhaitable.
                  default: "[]"
                indexes:
                  type: array
                  items:
                    type: string
                  description: "Liste des index à utiliser pour le géocodage (parmi address, poi, parcel)"
                  default: "[]"
                type:
                  type: string
                  description: "Colonne contenant le type d’objet accepté pour le géocodage de la ligne (address)"
                  default: ""
                citycode:
                  type: string
                  description: "Colonne contenant le code INSEE de la commune à utiliser comme filtre (address, poi)"
                  default: ""
                postcode:
                  type: string
                  description: "Colonne contenant le code postal à utiliser comme filtre (address, poi)"
                  default: ""
                category:
                  type: string
                  description: "Colonne contenant la catégorie de POI à utiliser comme filtre (poi)"
                  default: ""
                lon:
                  type: string
                  description: "Colonne contenant la longitude du point de recherche"
                  default: ""
                lat:
                  type: string
                  description: "Colonne contenant la latitude du point de recherche"
                  default: ""
                departmentcode:
                  type: string
                  description: "Colonne contenant le code département à utiliser comme filtre (parcel)"
                  default: ""
                municipalitycode:
                  type: string
                  description: "Colonne contenant le code commune  à utiliser comme filtre (parcel)"
                  default: ""
                oldmunicipalitycode:
                  type: string
                  description: "Colonne contenant l'ancien code commune à utiliser comme filtre (parcel)"
                  default: ""
                districtcode:
                  type: string
                  description: "Colonne contenant le code d'arrondissement à utiliser comme filtre (parcel)"
                  default: ""
                section:
                  type: string
                  description: "Colonne contenant le numéro de section à utiliser comme filtre (parcel)"
                  default: ""
                sheet:
                  type: string
                  description: "Colonne contenant le numéro de feuille à utiliser comme filtre (parcel)"
                  default: ""
                number:
                  type: string
                  description: "Colonne contenant le numéro de parcelle à utiliser comme filtre (parcel)"
                  default: ""
                result_columns:
                  type: array
                  items:
                    type: string
                  description: |
                    Liste des colonnes de type résultat à conserver dans le fichier CSV de sortie.

                    Par défaut toutes les colonnes disponibles sont retournées.
                  default: "[]"
            encoding:
              columns:
                style: form
                explode: true
              result_columns:
                style: form
                explode: true
              indexes:
                style: form
                explode: true
      responses:
        "200":
          description: Géocodage réussi
          content:
            text/csv:
              schema:
                $ref: "#/components/schemas/GeocodeCsvResponse"

        "400":
          description: "Échec du géocodage suite à une erreur dans la requête ou dans le fichier CSV"
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 400
                    description: Code d'erreur (HTTP)
                  message:
                    type: string
                    description: "Message d'erreur"
                    example: Impossible de lire le fichier CSV

  /reverse/csv:
    post:
      tags:
        - reverse
        - batch
      summary: Géocodage inversé en masse d’un fichier CSV
      description: |
        Géocodage inversé en masse d’un fichier CSV. Les paramètres de la requête permettent de spécifier les colonnes à utiliser pour le géocodage, les index à utiliser, les filtres à appliquer et les colonnes à conserver dans le fichier CSV de sortie.

        Le fichier soumis doit faire une taille maximale de 50 Mo.
      operationId: reverseCsv
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: string
                  format: binary
                  description: "Fichier CSV contenant les données à géocoder"
                indexes:
                  type: array
                  items:
                    type: string
                  description: "Liste des index à utiliser pour le géocodage (parmi address, poi, parcel)"
                  default: "[]"
                type:
                  type: string
                  description: "Colonne contenant le type d’objet accepté pour le géocodage de la ligne (address)"
                  default: ""
                citycode:
                  type: string
                  description: "Colonne contenant le code INSEE de la commune à utiliser comme filtre (address, poi)"
                  default: ""
                postcode:
                  type: string
                  description: "Colonne contenant le code postal à utiliser comme filtre (address, poi)"
                  default: ""
                category:
                  type: string
                  description: "Colonne contenant la catégorie de POI à utiliser comme filtre (poi)"
                  default: ""
                lon:
                  type: string
                  description: "Colonne contenant la longitude du point de recherche"
                  default: ""
                lat:
                  type: string
                  description: "Colonne contenant la latitude du point de recherche"
                  default: ""
                departmentcode:
                  type: string
                  description: "Colonne contenant le code département à utiliser comme filtre (parcel)"
                  default: ""
                municipalitycode:
                  type: string
                  description: "Colonne contenant le code commune  à utiliser comme filtre (parcel)"
                  default: ""
                oldmunicipalitycode:
                  type: string
                  description: "Colonne contenant l'ancien code commune à utiliser comme filtre (parcel)"
                  default: ""
                districtcode:
                  type: string
                  description: "Colonne contenant le code d'arrondissement à utiliser comme filtre (parcel)"
                  default: ""
                section:
                  type: string
                  description: "Colonne contenant le numéro de section à utiliser comme filtre (parcel)"
                  default: ""
                sheet:
                  type: string
                  description: "Colonne contenant le numéro de feuille à utiliser comme filtre (parcel)"
                  default: ""
                number:
                  type: string
                  description: "Colonne contenant le numéro de parcelle à utiliser comme filtre (parcel)"
                  default: ""
                result_columns:
                  type: array
                  items:
                    type: string
                  description: |
                    Liste des colonnes de type résultat à conserver dans le fichier CSV de sortie.

                    Par défaut toutes les colonnes disponibles sont retournées.
                  default: "[]"
            encoding:
              result_columns:
                style: form
                explode: true
              indexes:
                style: form
                explode: true
      responses:
        "200":
          description: Géocodage réussi
          content:
            text/csv:
              schema:
                $ref: "#/components/schemas/GeocodeCsvResponse"

        "400":
          description: "Échec du géocodage suite à une erreur dans la requête ou dans le fichier CSV"
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 400
                    description: Code d'erreur (HTTP)
                  message:
                    type: string
                    description: "Message d'erreur"
                    example: Impossible de lire le fichier CSV

  /async/projects:
    post:
      tags:
        - batch-async
      summary: Créer un nouveau projet
      description: |
        Cette requête permet de créer le projet de géocodage. Elle peut être réalisée de façon anonyme ou avec un jeton Géoplateforme valide.

        Si la requête est authentifiée avec l'en-tête Authorization alors il est possible de renseigner une communauté (Géoplateforme) de rattachement grâce à l'en-tête X-Community. Dans ce cas le projet hérite des quotas attribués à la communauté (taille max de fichier géocodage, niveau de parallélisation du géocodage). Par défaut un projet autorise un fichier de 50 Mo et ne propose pas de parallélisation (concurrency = 1).

        Lorsque le projet est créé avec un utilisateur authentifié, ce dernier recevra la notification de succès ou d'échec sur la boîte courriel renseignée avec son compte.

        À ce stade le projet est retourné avec un jeton qui doit être conservé pour les prochains appels du processus.
      parameters:
        - name: X-Community
          in: header
          required: false
          schema:
            type: string
      security:
        - {}
        - BearerAuth: []
      responses:
        '201':
          description: Projet créé avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        "401":
          description: Authentification incorrecte
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 401
                    description: Code d'erreur (HTTP)
                  message:
                    type: string
                    description: "Message d'erreur"
                    example: Invalid token
        "403":
          description: Droits insuffisants
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 403
                    description: Code d'erreur (HTTP)
                  message:
                    type: string
                    description: "Message d'erreur"
                    example: User is not a member of this community

  /async/projects/{projectId}:
    get:
      tags:
        - batch-async
      summary: Récupérer les informations
      description: |
        Permet la récupération des informations d'un projet :
        - métadonnées
        - état et progression du géocodage
        - fichier source et fichier résultat (notamment le jeton d'accès)
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
      security:
        - ProjectAuth: []
      responses:
        '200':
          description: Métadonnées du projet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Non autorisé
        '404':
          description: Projet introuvable

    delete:
      tags:
        - batch-async
      summary: Supprimer un projet
      description: |
        Permet la suppression d'un projet inactif (idle), terminé (completed) ou en erreur (failed).
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
      security:
        - ProjectAuth: []
      responses:
        '204':
          description: Projet supprimé avec succès
        '401':
          description: Non autorisé
        '403':
          description: Action interdite (le projet est en cours de traitement)
        '404':
          description: Projet introuvable

  /async/projects/{projectId}/pipeline:
    put:
      tags:
        - batch-async
      summary: Définir les paramètres du traitement
      description: |
        Permet de définir les paramètres de géocodage mais aussi le format de sortie (CSV ou GeoJSON).

        Dans le cas du CSV, les paramètres du fichier d'entrée sont conservés à l'exception de l'encodage qui sera toujours de l'UTF-8.

        Attention : l'adéquation des paramètres de géocodage avec le fichier fourni n'est vérifiée qu'au moment du géocodage.
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
      security:
        - ProjectAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pipeline'
      responses:
        '200':
          description: Pipeline défini avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Paramètres invalides
        '401':
          description: Non autorisé
        '403':
          description: Action interdite (le projet est en cours de traitement ou terminé)
        '404':
          description: Projet introuvable

  /async/projects/{projectId}/input-file:
    put:
      tags:
        - batch-async
      summary: Uploader un fichier d'entrée pour un projet
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
        - name: Content-Length
          in: header
          description: La taille du fichier peut être transmise pour s'assurer du transfert complet du fichier.
          required: false
          schema:
            type: integer
        - name: Content-Disposition
          in: header
          description: |
            Le nom du fichier à géocoder peut être transmis pour faciliter le suivi. Le fichier résultat reprendra en partie ce nom. Par défaut le fichier sera nommé input.csv.
          required: false
          schema:
            type: string
      security:
        - ProjectAuth: []
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Fichier d'entrée uploadé avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Fichier invalide (taille excessive ou incorrecte)
        '401':
          description: Non autorisé
        '403':
          description: Action interdite (le projet est en cours de traitement ou terminé)
        '404':
          description: Projet introuvable

  /async/projects/{projectId}/start:
    post:
      tags:
        - batch-async
      summary: Démander le démarrage du géocodage
      description: |
        Permet de signifier à la plateforme que le géocodage est prêt à être effectué. Il faut au préalable que le fichier source ait été soumis, ainsi que les paramètres du traitement.

        L'opération peut être annulée via la requête adéquate.
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
      security:
        - ProjectAuth: []
      responses:
        '200':
          description: Projet mis en attente de géocodage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Non autorisé
        '403':
          description: Action interdite (le projet est en cours de traitement ou terminé ou des éléments sont manquants)
        '404':
          description: Projet introuvable

  /async/projects/{projectId}/abort:
    post:
      tags:
        - batch-async
      summary: Annuler un géocodage en attente ou en cours
      description: |
        Permet d'annuler un géocodage en attente (waiting) ou en cours (processing). Dans ce cas il retourne à l'état inactif et peut être modifié ou supprimé.
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
      security:
        - ProjectAuth: []
      responses:
        '200':
          description: Annulation prise en compte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Non autorisé
        '403':
          description: Action interdite (le projet n'est pas en cours ou en attente)
        '404':
          description: Projet introuvable

  /async/projects/{projectId}/reset:
    post:
      tags:
        - batch-async
      summary: Ré-initialise un géocodage terminé ou en erreur
      description: |
        Permet de ré-initialiser un géocodage terminé (completed) ou en erreur (failed). Dans ce cas il retourne à l'état inactif et peut être modifié ou supprimé.
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
      security:
        - ProjectAuth: []
      responses:
        '200':
          description: Ré-initialisation prise en compte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Non autorisé
        '403':
          description: Action interdite (le projet n'est pas terminé ou en erreur)
        '404':
          description: Projet introuvable

  /async/projects/{projectId}/input-file/{token}:
    get:
      tags:
        - batch-async
      summary: Télécharger le fichier source du projet
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
        - name: token
          description: Jeton de sécurité du fichier accessible dans les métadonnées du projet (inputFile.token)
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Fichier téléchargé avec succès
          content:
            text/csv:
              schema:
                $ref: "#/components/schemas/GeocodeCsvResponse"
            application/json:
              schema:
                type: string
                format: binary

  /async/projects/{projectId}/output-file/{token}:
    get:
      tags:
        - batch-async
      summary: Télécharger le fichier résultat du projet
      parameters:
        - name: projectId
          description: Identifiant unique du projet
          in: path
          required: true
          schema:
            type: string
        - name: token
          description: Jeton de sécurité du fichier accessible dans les métadonnées du projet (outputFile.token)
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Fichier téléchargé avec succès
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

components:
  securitySchemes:
    ProjectAuth:
      type: apiKey
      name: Authorization
      in: header
      description: Token XXXXXX
    BearerAuth:
      type: apiKey
      name: Authorization
      in: header
      description: Bearer XXXXXX
  schemas:
    Getcapabilities:
      type: "object"
      properties:
        info:
          type: "object"
          properties:
            name:
              type: "string"
            url:
              type: "string"
            description:
              type: "string"
        api:
          type: "object"
          properties:
            name:
              type: "string"
              example: "rest"
            version:
              type: "string"
              example: "0.0.0"
        operations:
          type: "array"
          items:
            type: "object"
            properties:
              id:
                type: "string"
              description:
                type: "string"
              url:
                type: "string"
              methods:
                type: "array"
                items:
                  type: "string"
                  enum: ["GET", "POST", "PUT", "DELETE"]
              parameters:
                type: "array"
                items:
                  type: "object"
                  properties:
                    name:
                      type: "string"
                    in:
                      type: "string"
                    description:
                      type: "string"
                    required:
                      type: "boolean"
                    default:
                      description: "default value"
                    schema:
                      type: "object"
                      properties:
                        type:
                          type: "string"
                        example:
                          type: "string"
                    example:
                      type: "string"
        indexes:
          type: "array"
          items:
            type: "object"
            properties:
              id:
                type: "string"
              description:
                type: "string"
              fields:
                type: "array"
                items:
                  type: "object"
                  properties:
                    name:
                      type: "string"
                    description:
                      type: "string"
                    type:
                      type: "string"
                    queryable:
                      type: "boolean"
                    filter:
                      type: "boolean"
                    values:
                      type: "array"
                      items:
                        description: allowed value

    GeocodeResponse:
      type: object
      oneOf:
        - $ref: "#/components/schemas/Address"
        - $ref: "#/components/schemas/Poi"
        - $ref: "#/components/schemas/Parcel"

    GeocodeReverseResponse:
      type: object
      oneOf:
        - $ref: "#/components/schemas/AddressReverse"
        - $ref: "#/components/schemas/PoiReverse"
        - $ref: "#/components/schemas/ParcelReverse"

    Parcel:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: "#/components/schemas/ParcelProperties"
        geometry:
          $ref: "#/components/schemas/GeometryPoint"

    ParcelProperties:
      type: object
      properties:
        id:
          type: string
          description: "Identifiant de la parcelle"
        departmentcode:
          type: string
          description: "Code du département"
        municipalitycode:
          type: string
          description: "Code de la commune"
        city:
          type: string
          description: "Nom de la commune"
        oldmunicipalitycode:
          type: string
          description: "Code de l'ancienne commune"
        districtcode:
          type: string
          description: "Code insee de l'arrondissement"
        section:
          type: string
          description: "Section cadastrale"
        number:
          type: string
          description: "Numéro cadastral"
        sheet:
          type: string
          description: "Feuille cadastrale"
        truegeometry:
          $ref: "#/components/schemas/GeometryPolygon"
        _score:
          type: number
        _type:
          type: string
          enum: ["parcel"]
      example:
        id: "75056104AV0133"
        departmentcode: "75"
        municipalitycode: "056"
        city: Paris
        oldmunicipalitycode: "000"
        districtcode: "104"
        section: "AV"
        number: "133"
        sheet: 1
        truegeometry:
          {
            "type": "Polygon",
            "coordinates":
              [
                [
                  [2.35457222187139, 48.8523027661354],
                  [2.35463049659443, 48.8523731401755],
                  [2.35465580843827, 48.8523650925735],
                  [2.35464724014948, 48.8522756505323],
                  [2.35457222187139, 48.8523027661354],
                ],
              ],
          }
        _score: 1
        _type: "parcel"

    ParcelReverse:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: "#/components/schemas/ParcelReverseProperties"
        geometry:
          $ref: "#/components/schemas/GeometryPoint"

    ParcelReverseProperties:
      type: object
      properties:
        id:
          type: string
          description: "Identifiant de la parcelle"
        departmentcode:
          type: string
          description: "Code du département"
        municipalitycode:
          type: string
          description: "Code de la commune"
        city:
          type: string
          description: "Nom de la commune"
        oldmunicipalitycode:
          type: string
          description: "Code de l'ancienne commune"
        districtcode:
          type: string
          description: "Code insee de l'arrondissement"
        section:
          type: string
          description: "Section cadastrale"
        number:
          type: string
          description: "Numéro cadastral"
        sheet:
          type: string
          description: "Feuille cadastrale"
        truegeometry:
          $ref: "#/components/schemas/GeometryPolygon"
        _score:
          type: number
        _type:
          type: string
          enum: ["parcel"]
        distance:
          type: number
      example:
        id: "75056104AV0133"
        departmentcode: "75"
        municipalitycode: "056"
        city: Paris
        oldmunicipalitycode: "000"
        districtcode: "104"
        section: "AV"
        number: "133"
        sheet: 1
        truegeometry:
          {
            "type": "Polygon",
            "coordinates":
              [
                [
                  [2.35457222187139, 48.8523027661354],
                  [2.35463049659443, 48.8523731401755],
                  [2.35465580843827, 48.8523650925735],
                  [2.35464724014948, 48.8522756505323],
                  [2.35457222187139, 48.8523027661354],
                ],
              ],
          }
        _score: 1
        _type: "parcel"
        distance: 100

    Address:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: "#/components/schemas/AddressProperties"
        geometry:
          $ref: "#/components/schemas/GeometryPoint"
    AddressProperties:
      type: object
      properties:
        label:
          type: string
          description: "Libellé complet de l'adresse"
        id:
          type: string
        postcode:
          $ref: "#/components/schemas/PostalCode"
        city:
          type: string
          description: "Commune de l'adresse"
        district:
          type: string
          description: "Arrondissement de l'adresse"
        street:
          type: string
          description: "Rue de l'adresse"
        housenumber:
          type: string
        citycode:
          $ref: "#/components/schemas/InseeCode"
        x:
          type: number
          description: "Longitude de l'adresse"
        y:
          type: number
          description: "Latitude de l'adresse"
        score:
          type: number
        _score:
          type: number
        name:
          type: string
        type:
          type: string
          enum: ["housenumber", "street", "locality", "municipality"]
        _type:
          type: string
          enum: ["address"]
          description: "Rétro-compatibilité"
        context:
          type: string
        importance:
          type: number
      example:
        label: "10 Rue Nationale 75013 Paris 13e Arrondissement"
        id: "test-id"
        postcode: "75013"
        city: "Paris"
        district: "Paris 13e Arrondissement"
        street: "Rue Nationale"
        housenumber: "10"
        citycode: "75113"
        x: 2.369063
        y: 48.822409
        score: 0.6515151515151515
        _score: 0.6515151515151515
        name: "10 Rue Nationale"
        type: "housenumber"
        _type: "address"
        contexte: "75, Paris"
        importance: "0.6"

    AddressReverse:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: "#/components/schemas/AddressReverseProperties"
        geometry:
          $ref: "#/components/schemas/GeometryPoint"
    AddressReverseProperties:
      type: object
      properties:
        label:
          type: string
          description: "Libellé complet de l'adresse"
        id:
          type: string
        postcode:
          $ref: "#/components/schemas/PostalCode"
        city:
          type: string
          description: "Commune de l'adresse"
        district:
          type: string
          description: "Arrondissement de l'adresse"
        street:
          type: string
          description: "Rue de l'adresse"
        housenumber:
          type: string
        citycode:
          $ref: "#/components/schemas/InseeCode"
        x:
          type: number
          description: "Longitude de l'adresse"
        y:
          type: number
          description: "Latitude de l'adresse"
        score:
          type: number
        _score:
          type: number
        name:
          type: string
        type:
          type: string
          enum: ["housenumber", "street", "locality", "municipality"]
        _type:
          type: string
          enum: ["address"]
          description: "Rétro-compatibilité"
        context:
          type: string
        importance:
          type: number
        distance:
          type: number
      example:
        label: "10 Rue Nationale 75013 Paris 13e Arrondissement"
        id: "test-id"
        postcode: "75013"
        city: "Paris"
        district: "Paris 13e Arrondissement"
        street: "Rue Nationale"
        housenumber: "10"
        citycode: "75113"
        x: 2.369063
        y: 48.822409
        score: 0.6515151515151515
        _score: 0.6515151515151515
        name: "10 Rue Nationale"
        type: "housenumber"
        _type: "address"
        contexte: "75, Paris"
        importance: "0.6"
        distance: 100

    Poi:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: "#/components/schemas/PoiProperties"
        geometry:
          $ref: "#/components/schemas/GeometryPoint"
    PoiProperties:
      type: object
      properties:
        toponym:
          type: string
          description: "Libellé du toponyme"
        postcode:
          type: array
          items:
            $ref: "#/components/schemas/PostalCode"
        citycode:
          type: array
          items:
            $ref: "#/components/schemas/InseeCode"
        city:
          type: array
          items:
            type: string
        category:
          $ref: "#/components/schemas/PoiType"
        extrafields:
          type: object
        truegeometry:
          $ref: "#/components/schemas/Geometry"
        _score:
          type: number
        _type:
          type: string
          enum: ["poi"]
      example:
        toponym: "Pont National"
        postcode: [77310, 91100]
        citycode: [77, 77300, 91, 91450]
        city: ["Saint-Fargeau-Ponthierry", "Corbeil-Essonnes"]
        category: ["construction linéaire"]
        extrafields:
          {
            "names": ["pont strasbourg", "pont national"],
            "cleabs": "CONSLINE0000000060494180",
          }
        truegeometry:
          {
            "coordinates":
              [
                [2.03666899913969, 44.3490469250535, 257],
                [2.03646952056093, 44.3492684335352, 256.3],
                [2.03644906780383, 44.3492907599887, 256.3],
                [2.03630075804051, 44.3494542018237, 256.3],
              ],
            "type": "LineString",
          }
        _score: 0.5757575757575758
        _type: "poi"

    PoiReverse:
      type: object
      properties:
        type:
          type: string
          example: Feature
        properties:
          $ref: "#/components/schemas/PoiReverseProperties"
        geometry:
          $ref: "#/components/schemas/GeometryPoint"
    PoiReverseProperties:
      type: object
      properties:
        toponym:
          type: string
          description: "Libellé du toponyme"
        postcode:
          type: array
          items:
            $ref: "#/components/schemas/PostalCode"
        citycode:
          type: array
          items:
            $ref: "#/components/schemas/InseeCode"
        city:
          type: array
          items:
            type: string
        category:
          $ref: "#/components/schemas/PoiType"
        extrafields:
          type: object
        truegeometry:
          $ref: "#/components/schemas/Geometry"
        _score:
          type: number
        _type:
          type: string
          enum: ["poi"]
        distance:
          type: number
      example:
        toponym: "Pont National"
        postcode: [77310, 91100]
        citycode: [77, 77300, 91, 91450]
        city: ["Saint-Fargeau-Ponthierry", "Corbeil-Essonnes"]
        category: ["construction linéaire"]
        extrafields:
          {
            "names": ["pont strasbourg", "pont national"],
            "cleabs": "CONSLINE0000000060494180",
          }
        truegeometry:
          {
            "coordinates":
              [
                [2.03666899913969, 44.3490469250535, 257],
                [2.03646952056093, 44.3492684335352, 256.3],
                [2.03644906780383, 44.3492907599887, 256.3],
                [2.03630075804051, 44.3494542018237, 256.3],
              ],
            "type": "LineString",
          }
        _score: 0.5757575757575758
        _type: "poi"
        distance: 100

    PoiType:
      type: array
      items:
        type: string

    PostalCode:
      maxLength: 5
      minLength: 5
      type: string
      description: "Code postal"

    InseeCode:
      maxLength: 5
      minLength: 2
      type: string
      description: "Code INSEE"

    DepCode:
      maxLength: 3
      minLength: 2
      type: string
      description: "Code du département"

    Geometry:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/GeometryType"
        coordinates:
          type: array
          items:
            type: number
      example:
        type: "Point"
        coordinates: [2.03648539635326, 44.3492508045369]

    GeometryPoint:
      type: object
      properties:
        type:
          type: string
          enum: ["Point"]
        coordinates:
          type: array
          items:
            type: number
      example:
        type: "Point"
        coordinates: [2.03648539635326, 44.3492508045369]

    GeometryCircle:
      type: object
      properties:
        type:
          type: string
          enum: ["Circle"]
        coordinates:
          type: array
          items:
            type: number
        radius:
          type: number
      example:
        type: "Circle"
        coordinates: [2.35457222187139, 48.8523027661354]
        radius: 100

    GeometryLineString:
      type: object
      properties:
        type:
          type: string
          enum: ["LineString"]
        coordinates:
          type: array
          items:
            type: number
      example:
        type: "LineString"
        coordinates:
          [
            [2.35457222187139, 48.8523027661354],
            [2.35463049659443, 48.8523731401755],
            [2.35457222187139, 48.8523027661354],
          ]

    GeometryPolygon:
      type: object
      properties:
        type:
          type: string
          enum: ["Polygon"]
        coordinates:
          type: array
          items:
            type: number
      example:
        type: "Polygon"
        coordinates:
          [
            [
              [2.35457222187139, 48.8523027661354],
              [2.35463049659443, 48.8523731401755],
              [2.35465580843827, 48.8523650925735],
              [2.35464724014948, 48.8522756505323],
              [2.35457222187139, 48.8523027661354],
            ],
          ]

    GeometryMultiPolygon:
      type: object
      properties:
        type:
          type: string
          enum: ["MultiPolygon"]
        coordinates:
          type: array
          items:
            type: number
      example:
        type: "MultiPolygon"
        coordinates:
          [
            [
              [
                [2.35457222187139, 48.8523027661354],
                [2.35463049659443, 48.8523731401755],
                [2.35465580843827, 48.8523650925735],
                [2.35457222187139, 48.8523027661354],
              ],
            ],
          ]

    GeometryType:
      type: string
      enum:
        - Point
        - MultiPolygon
        - LineString

    Index:
      type: string
      enum:
        - address
        - poi
        - parcel
      default: address

    HouseNumberInfos:
      type: object
      properties:
        date:
          type: string
        kind:
          $ref: "#/components/schemas/AddressPositionKing"
        source:
          type: string

    AddressPositionKing:
      type: array
      items:
        type: string
        enum:
          - entrance
          - building
          - staircase
          - unit
          - parcel
          - segment
          - utility
          - area
          - postal
          - unknown

    Project:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [idle, waiting, processing, failed, completed]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        params:
          $ref: '#/components/schemas/ProjectParams'
        pipeline:
          $ref: '#/components/schemas/Pipeline'
        inputFile:
          type: object
        outputFile:
          type: object
        processing:
          $ref: '#/components/schemas/GeocodeProcessing'
        token:
          type: string
          description: Jeton permettant d'interéagir avec le projet. N'est retourné que lors de la création.

    GeocodeProcessing:
      type: object
      properties:
        step:
          type: string
        validationProgress:
          type: object
        validationError:
          type: string
        geocodingProgress:
          type: object
        geocodingError:
          type: string
        globalError:
          type: string
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        heartbeat:
          type: string
          format: date-time

    Pipeline:
      type: object
      properties:
        geocodeOptions:
          type: object
          properties:
            operation:
              type: string
              description: Opération demandée
              enum: [search, reverse]
              default: search
            indexes:
              type: array
              description: Index à utiliser pour le géocodage
              items:
                type: string
                enum: [address, poi, parcel]
            columns:
              type: array
              items:
                type: string
              description: |
                Liste des colonnes du fichier CSV à utiliser pour le géocodage. Celles-ci seront concaténées pour former le critère de recherche texte.

                Si le paramètre n'est pas fourni toutes les colonnes seront concaténées, ce qui est rarement souhaitable.
            type:
              type: string
              description: "Colonne contenant le type d’objet accepté pour le géocodage de la ligne (address)"
            citycode:
              type: string
              description: "Colonne contenant le code INSEE de la commune à utiliser comme filtre (address, poi)"
            postcode:
              type: string
              description: "Colonne contenant le code postal à utiliser comme filtre (address, poi)"
            category:
              type: string
              description: "Colonne contenant la catégorie de POI à utiliser comme filtre (poi)"
            lon:
              type: string
              description: "Colonne contenant la longitude du point de recherche"
            lat:
              type: string
              description: "Colonne contenant la latitude du point de recherche"
            departmentcode:
              type: string
              description: "Colonne contenant le code département à utiliser comme filtre (parcel)"
            municipalitycode:
              type: string
              description: "Colonne contenant le code commune  à utiliser comme filtre (parcel)"
            oldmunicipalitycode:
              type: string
              description: "Colonne contenant l'ancien code commune à utiliser comme filtre (parcel)"
            districtcode:
              type: string
              description: "Colonne contenant le code d'arrondissement à utiliser comme filtre (parcel)"
            section:
              type: string
              description: "Colonne contenant le numéro de section à utiliser comme filtre (parcel)"
            sheet:
              type: string
              description: "Colonne contenant le numéro de feuille à utiliser comme filtre (parcel)"
            number:
              type: string
              description: "Colonne contenant le numéro de parcelle à utiliser comme filtre (parcel)"
            result_columns:
              type: array
              items:
                type: string
              description: |
                Liste des colonnes de type résultat à conserver dans le fichier de sortie.

                Par défaut toutes les colonnes disponibles sont retournées.
        outputFormat:
          type: string
          enum: [csv, geojson]

    ProjectParams:
      type: object
      properties:
        maxInputFileSize:
          type: string
          enum: [50MB, 100MB, 200MB, 500MB, 1GB]
        concurrency:
          type: number
          enum: [1, 2, 4]

    GeocodeCsvResponse:
      type: string
      format: binary
      description: |
        Fichier CSV géocodé. Les lignes d'origine sont préservées.

        Les colonnes issues de l'objet associé lors du géocodage et pouvant être ajoutées sont :
        - result_label
        - result_score
        - result_type (address)
        - result_id
        - result_housenumber (address)
        - result_name (address)
        - result_street (address)
        - result_postcode (address, poi)
        - result_city (address, poi)
        - result_context
        - result_citycode (address, poi)
        - result_oldcitycode (address, poi)
        - result_oldcity (address, poi)
        - result_district (address, poi)
        - result_category (poi)
        - result_departmentcode (parcel)
        - result_municipalitycode (parcel)
        - result_section (parcel)
        - result_sheet (parcel)
        - result_number (parcel)
        - result_oldmunicipalitycode (parcel)
        - result_districtcode (parcel)

        Les colonnes suivantes sont spécifiques au géocodage direct :
        - latitude
        - longitude

        Les colonnes suivantes sont spécifiques au géocodage inversé :
        - result_latitude
        - result_longitude
        - result_distance

        Les colonnes suivantes sont liées au géocodage en masse :
        - result_score_next : score du résultat suivant le cas échéant
        - result_index : index dans lequel l'objet a été trouvé
        - result_status (ok = trouvé, not-found = non trouvé, skipped = ligne ignorée en raison de paramètres manquants ou invalides, error = erreur du serveur lors de la recherche)

        NB : En cas de colonnes d'origine nommées latitude ou longitude et de géocodage direct, elles seront écrasées par les valeurs calculées.