definition.yml

swagger: '2.0'
info:
  title: API Géo
  version: '1.0'
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
        - codesPostaux
        - centre
        - surface
        - contour
        - codeDepartement
        - departement
        - codeRegion
        - region
        - population
    collectionFormat: csv
    default:
      - nom
      - code
      - codesPostaux
      - codeDepartement
      - codeRegion
      - population
  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
    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
    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']
    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: 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/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'

  /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/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:
            $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/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/Departement'
        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:
            $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
      codeDepartement:
        type: string
        description: Code du département associé à la commune
      codeRegion:
        type: string
        description: Code de la région associée à la commune
      departement:
        $ref: '#/definitions/Departement'
      region:
        $ref: '#/definitions/Region'
      population:
        type: integer
        description: Population municipale
      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)
  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