definition.yml

swagger: '2.0'
info:
  title: API Géo
  version: '1.1'
host: geo.api.gouv.fr
schemes:
  - https
produces:
  - application/json
parameters:
  communeFieldsParam:
    name: fields
    in: query
    description: Liste des champs souhaités dans la réponse
    type: array
    items:
      type: string
      enum:
        - nom
        - code
        - codeParent
        - codesPostaux
        - siren
        - centre
        - surface
        - contour
        - mairie
        - bbox
        - codeEpci
        - epci
        - codeDepartement
        - departement
        - codeRegion
        - region
        - population
        - anciensCodes
        - deleguees
        - associees
        - zone
    collectionFormat: csv
    default:
      - nom
      - code
      - codesPostaux
      - siren
      - codeEpci
      - codeDepartement
      - codeRegion
      - population
  communeAssocieeDelegueeFieldsParam:
    name: fields
    in: query
    description: Liste des champs souhaités dans la réponse
    type: array
    items:
      type: string
      enum:
        - nom
        - code
        - type
        - chefLieu
        - centre
        - surface
        - contour
        - bbox
        - codeEpci
        - epci
        - codeDepartement
        - departement
        - codeRegion
        - region
    collectionFormat: csv
    default:
      - nom
      - code
      - type
      - chefLieu
      - codeEpci
      - codeDepartement
      - codeRegion
  epciFieldsParam:
    name: fields
    in: query
    description: Liste des champs souhaités dans la réponse
    type: array
    items:
      type: string
      enum:
        - nom
        - code
        - population
        - financement
        - type
        - codesRegions
        - codesDepartements
        - centre
        - surface
        - contour
        - bbox
        - zone
    collectionFormat: csv
    default:
      - nom
      - code
      - codesRegions
      - codesDepartements
  departementFieldsParam:
    name: fields
    in: query
    description: Liste des champs souhaités dans la réponse
    type: array
    items:
      type: string
      enum:
        - nom
        - code
        - codeRegion
        - region
        - zone
        - chefLieu
    collectionFormat: csv
    default:
      - nom
      - code
      - codeRegion
  regionFieldsParam:
    name: fields
    in: query
    description: Liste des champs souhaités dans la réponse
    type: array
    items:
      type: string
      enum:
        - nom
        - code
        - zone
        - chefLieu
    collectionFormat: csv
    default:
      - nom
      - code
  formatParam:
    name: format
    in: query
    description: Format de réponse attendu
    type: string
    enum: ['json', 'geojson']
    default: json
  communeGeometryParam:
    name: geometry
    in: query
    description: Géométrie à utiliser pour la sortie géographique
    type: string
    enum: ['centre', 'contour', 'mairie', 'bbox']
    default: centre
  communeAssocieeDelegueeGeometryParam:
    name: geometry
    in: query
    description: Géométrie à utiliser pour la sortie géographique
    type: string
    enum: ['centre', 'contour', 'bbox']
    default: centre
  typeCommune:
    name: type
    in: query
    description: Type permettant de filtrer si on retourne les communes, les arrondissements ou les 2. Par défaut à commune-actuelle.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum: ['commune-actuelle', 'arrondissement-municipal']
  typeCommuneAssocieeDeleguee:
    name: type
    in: query
    description: Type permettant de filtrer si on retourne les communes, les arrondissements ou les 2. Par défaut à commune-actuelle.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum: ['commune-associee', 'commune-deleguee']
  zoneParam:
    name: zone
    in: query
    description: Zone permettant de filtrer à la métropole, aux DROM et aux COM. Défaut à metro,drom sauf pour les communes à metro,drom,com pour conserver le comportement historique.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum: ['metro', 'drom', 'com']
  epciGeometryParam:
    name: geometry
    in: query
    description: Géométrie à utiliser pour la sortie géographique
    type: string
    enum: ['centre', 'contour', 'bbox']
    default: centre
  limitParam:
    name: limit
    in: query
    description: Nombre d'éléments à retourner
    type: integer
    format: int32
    default: 0
paths:
  /communes:
    get:
      summary: Recherche des communes
      tags:
        - Communes
      parameters:
        - name: codePostal
          in: query
          description: Code postal associé
          type: string
        - name: lat
          in: query
          description: Latitude (en degrés)
          type: number
          format: float
        - name: lon
          in: query
          description: Longitude (en degrés)
          type: number
          format: float
        - name: nom
          in: query
          description: Nom de la commune
          type: string
        - name: boost
          in: query
          description: Mode de boost de la recherche par nom
          type: string
        - name: code
          in: query
          description: Code de la commune
          type: string
        - name: siren
          in: query
          description: Code SIREN de la commune
          type: string
        - name: codeEpci
          in: query
          description: Code de l'EPCI associé
          type: string
        - name: codeDepartement
          in: query
          description: Code du département associé
          type: string
        - name: codeRegion
          in: query
          description: Code de la région associée
          type: string
        - name: codeParent
          in: query
          description: Code de la commune si on a un arrondissement
          type: string
        - name: ancienCode
          in: query
          description: Code INSEE ancien de la commune
          type: string
        - $ref: '#/parameters/zoneParam'
        - $ref: '#/parameters/typeCommune'
        - $ref: '#/parameters/communeFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/communeGeometryParam'
      responses:
        200:
          description: Liste de communes
          schema:
            type: array
            items:
              $ref: '#/definitions/Commune'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'


  /communes/{code}:
    get:
      summary: Récupérer les informations concernant une commune
      tags:
        - Communes
      parameters:
        - name: code
          in: path
          description: Code INSEE de la commune
          required: true
          type: string
        - $ref: '#/parameters/communeFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/communeGeometryParam'
      responses:
        200:
          description: Informations concernant une commune
          schema:
            $ref: '#/definitions/Commune'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Commune introuvable
          schema:
            $ref: '#/definitions/Error'

  /communes_associees_deleguees:
    get:
      summary: Recherche des communes associées et/ou déléguées
      tags:
        - Communes associées et déléguées
      parameters:
        - name: lat
          in: query
          description: Latitude (en degrés)
          type: number
          format: float
        - name: lon
          in: query
          description: Longitude (en degrés)
          type: number
          format: float
        - name: nom
          in: query
          description: Nom de la commune
          type: string
        - name: code
          in: query
          description: Code de la commune
          type: string
        - name: codeEpci
          in: query
          description: Code de l'EPCI associé
          type: string
        - name: codeDepartement
          in: query
          description: Code du département associé
          type: string
        - name: codeRegion
          in: query
          description: Code de la région associée
          type: string
        - $ref: '#/parameters/typeCommuneAssocieeDeleguee'
        - $ref: '#/parameters/communeAssocieeDelegueeFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/communeAssocieeDelegueeGeometryParam'
      responses:
        200:
          description: Liste de communes associées et/ou déléguées
          schema:
            type: array
            items:
              $ref: '#/definitions/Commune'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'

  /communes_associees_deleguees/{code}:
    get:
      summary: Récupérer les informations concernant une commune associée ou déléguée
      tags:
        - Communes associées et déléguées
      parameters:
        - name: code
          in: path
          description: Code INSEE de la commune associée ou déléguée
          required: true
          type: string
        - $ref: '#/parameters/communeAssocieeDelegueeFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/communeAssocieeDelegueeGeometryParam'
      responses:
        200:
          description: Informations concernant une commune associée ou déléguée
          schema:
            $ref: '#/definitions/Commune'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Commune associée ou déléguée introuvable
          schema:
            $ref: '#/definitions/Error'

  /epcis:
    get:
      summary: Recherche des EPCI
      tags:
        - EPCI
      parameters:
        - name: nom
          in: query
          description: Nom de l'EPCI
          type: string
        - name: boost
          in: query
          description: Mode de boost de la recherche par nom
          type: string
        - name: codeEpci
          in: query
          description: Code de l'EPCI associé
          type: string
        - name: codeDepartement
          in: query
          description: Code du département associé
          type: string
        - name: codeRegion
          in: query
          description: Code de la région associée
          type: string
        - $ref: '#/parameters/zoneParam'
        - $ref: '#/parameters/epciFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/epciGeometryParam'
      responses:
        200:
          description: Liste des EPCI
          schema:
            type: array
            items:
              $ref: '#/definitions/Epci'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
  /epcis/{code}:
    get:
      summary: Récupérer les informations concernant un EPCI
      tags:
        - EPCI
      parameters:
        - name: code
          in: path
          description: Code INSEE de l'EPCI
          required: true
          type: string
        - $ref: '#/parameters/epciFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/epciGeometryParam'
      responses:
        '200':
          description: Informations concernant une commune
          schema:
            $ref: '#/definitions/Epci'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: EPCI introuvable
          schema:
            $ref: '#/definitions/Error'
  /epcis/{code}/communes:
    get:
      summary: Renvoi les communes d'un EPCI
      tags:
        - EPCI
        - Communes
      parameters:
        - name: code
          in: path
          description: Code de l'EPCI
          required: true
          type: string
        - $ref: '#/parameters/communeFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/communeGeometryParam'
      responses:
        200:
          description: Liste des communes de l'EPCI
          schema:
            type: array
            items:
              $ref: '#/definitions/Commune'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: EPCI introuvable
          schema:
            $ref: '#/definitions/Error'

  /departements:
      get:
        summary: Recherche des départements
        tags:
          - Départements
        parameters:
          - name: code
            in: query
            description: Code du département
            type: string
          - name: codeRegion
            in: query
            description: Code région associé
            type: string
          - name: nom
            in: query
            description: Nom du département
            type: string
          - $ref: '#/parameters/zoneParam'
          - $ref: '#/parameters/departementFieldsParam'
        responses:
          200:
            description: Le ou les départements
            schema:
              type: array
              items:
                $ref: '#/definitions/Departement'
          400:
            description: Erreur. Requête mal formée
            schema:
              $ref: '#/definitions/Error'

  /departements/{code}:
    get:
      summary: Récupérer les informations concernant un département
      tags:
        - Départements
      parameters:
        - name: code
          in: path
          description: Code du département
          required: true
          type: string
        - $ref: '#/parameters/departementFieldsParam'
      responses:
        200:
          description: Informations concernant un département
          schema:
            $ref: '#/definitions/Departement'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Département introuvable
          schema:
            $ref: '#/definitions/Error'

  /departements/{code}/communes:
    get:
      summary: Renvoi les communes d'un département
      tags:
        - Départements
        - Communes
      parameters:
        - name: code
          in: path
          description: Code du département
          required: true
          type: string
        - $ref: '#/parameters/communeFieldsParam'
        - $ref: '#/parameters/formatParam'
        - $ref: '#/parameters/communeGeometryParam'
      responses:
        200:
          description: Liste des communes du département
          schema:
            type: array
            items:
              $ref: '#/definitions/Commune'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Département introuvable
          schema:
            $ref: '#/definitions/Error'

  /regions:
      get:
        summary: Recherche des régions
        tags:
          - Régions
        parameters:
          - name: code
            in: query
            description: Code de la région
            type: string
          - name: nom
            in: query
            description: Nom de la région
            type: string
          - $ref: '#/parameters/zoneParam'
          - $ref: '#/parameters/regionFieldsParam'
        responses:
          200:
            description: La ou les régions
            schema:
              type: array
              items:
                $ref: '#/definitions/Region'
          400:
            description: Erreur. Requête mal formée
            schema:
              $ref: '#/definitions/Error'

  /regions/{code}:
    get:
      summary: Récupérer les informations concernant une région
      tags:
        - Régions
      parameters:
        - name: code
          in: path
          description: Code de la région
          required: true
          type: string
        - $ref: '#/parameters/regionFieldsParam'
      responses:
        200:
          description: Informations concernant la région
          schema:
            $ref: '#/definitions/Region'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Région introuvable
          schema:
            $ref: '#/definitions/Error'

  /regions/{code}/departements:
    get:
      summary: Renvoi les départements d'une région
      tags:
        - Départements
        - Régions
      parameters:
        - name: code
          in: path
          description: Code de la région
          required: true
          type: string
        - $ref: '#/parameters/regionFieldsParam'
      responses:
        200:
          description: Liste des départements de la région
          schema:
            type: array
            items:
              $ref: '#/definitions/Departement'
        400:
          description: Erreur. Requête mal formée
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Département introuvable
          schema:
            $ref: '#/definitions/Error'

definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
        description: Code HTTP de l'erreur
      message:
        type: string
        description: Libellé de l'erreur
      description:
        type: string
        description: Explication
  Commune:
    type: object
    properties:
      code:
        type: string
        description: Code INSEE de la commune
      nom:
        type: string
        description: Nom de la commune
      codesPostaux:
        type: array
        description: Liste des codes postaux associés à la commune
        items:
          type: string
      siren:
        type: string
        description: Code SIREN de la commune
      codeEpci:
        type: string
        description: Code de l'EPCI associé à la commune
      codeDepartement:
        type: string
        description: Code du département associé à la commune
      codeRegion:
        type: string
        description: Code de la région associée à la commune
      epci:
        $ref: '#/definitions/Epci'
      departement:
        $ref: '#/definitions/Departement'
      region:
        $ref: '#/definitions/Region'
      associees:
        type: array
        description: Liste des codes postaux associés à la commune
        items:
          type: object
          properties:
            code:
              type: string
            nom:
              type: string
      deleguees:
        type: array
        description: Liste des codes postaux associés à la commune
        items:
          type: object
          properties:
            code:
              type: string
            nom:
              type: string
      population:
        type: integer
        description: Population municipale
      anciensCodes:
        type: array
        description: Liste des anciens codes INSEE associés à la commune
        items:
          type: string
      surface:
        type: number
        format: float
        description: Surface de la commune, en hectares
      centre:
        type: object
        description: Centre de la commune (Point GeoJSON)
      contour:
        type: object
        description: Contour de la commune (Polygon GeoJSON)
      mairie:
        type: object
        description: Mairie principale de la commune (Point GeoJSON). Pour les COM et les communes mortes pour la France, on retourne le centre.
      bbox:
        type: object
        description: Rectangle englobant la commune (Polygon GeoJSON)
  CommuneAssocieeDeleguee:
    type: object
    properties:
      code:
        type: string
        description: Code INSEE de la commune associée ou déléguée
      nom:
        type: string
        description: Nom de la commune associée ou déléguée
      codeEpci:
        type: string
        description: Code de l'EPCI associé à la commune associée ou déléguée
      codeDepartement:
        type: string
        description: Code du département associé à la commune associée ou déléguée
      codeRegion:
        type: string
        description: Code de la région associée à la commune associée ou déléguée
      epci:
        $ref: '#/definitions/Epci'
      departement:
        $ref: '#/definitions/Departement'
      region:
        $ref: '#/definitions/Region'
      surface:
        type: number
        format: float
        description: Surface de la commune associée ou déléguée, en hectares
      centre:
        type: object
        description: Centre de la commune associée ou déléguée (Point GeoJSON)
      contour:
        type: object
        description: Contour de la commune associée ou déléguée (Polygon GeoJSON)
      bbox:
        type: object
        description: Rectangle englobant la commune associée ou déléguée (Polygon GeoJSON)
  Epci:
    type: object
    properties:
      code:
        type: string
        description: Code SIREN de l'EPCI
      nom:
        type: string
        description: Nom de l'EPCI
      type:
        type: string
        description: Type de l'EPCI, soit communauté d'agglomération (CA), soit communauté de communes (CC), soit communauté urbaine (CU), soit métropole de Lyon (MET69), soit métropole (METRO)
      financement:
        type: string
        description: Financement de l'EPCI, soit fiscalité additionnelle (FA), soit en fiscalité professionnelle unique (FPU)
      codesDepartements:
        type: array
        description: Liste des départements de l'EPCI
        items:
          type: string
      codesRegions:
        type: array
        description: Liste des régions de l'EPCI
        items:
          type: string
      population:
        type: integer
        description: Population municipale
      surface:
        type: number
        format: float
        description: Surface de l'EPCI, en hectares
      centre:
        type: object
        description: Centre de l'EPCI (Point GeoJSON)
      contour:
        type: object
        description: Contour de l'EPCI (Polygon GeoJSON)
      bbox:
        type: object
        description: Rectangle englobant la commune (Polygon GeoJSON)
  Departement:
    type: object
    properties:
      code:
        type: string
        description: Code du département
      nom:
        type: string
        description: Nom du département
      codeRegion:
        type: string
        description: Code de la région
      region:
        $ref: '#/definitions/Region'
  Region:
    type: object
    properties:
      code:
        type: string
        description: Code de la région
      nom:
        type: string
        description: Nom de la région