openapi: 3.0.3
info:
  title: wymmo.dev geodata
  description: |
    The French administrative divisions, regions, departements, communes and EPCI, with their contours, as geo.api.gouv.fr serves them:
    same paths, same parameters, same JSON, faster.

    Data:
    - the official geographic code 2026 and the legal populations of the Insee, with the EPCI of the DGCL and the postal codes of La Poste,
      through `@etalab/decoupage-administratif` 6.0.0, [Licence Ouverte 2.0](https://www.etalab.gouv.fr/licence-ouverte-open-licence);
    - the contours, centres and town halls of the communes and EPCI, `contours-administratifs` 2026 of Etalab:
      generalized from ADMIN EXPRESS 4.0 of the IGN (2026-01-19), Licence Ouverte 2.0, for mainland France and the overseas departments;
      for the communes of Saint-Pierre-et-Miquelon (975), Saint-Barthélemy (977), Saint-Martin (978), the TAAF (984), Wallis-et-Futuna (986) and Clipperton (989),
      taken from OpenStreetMap, © OpenStreetMap contributors, [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/);
      for those of French Polynesia (987) and New Caledonia (988), from their local services, licence not verified at the source;
      the town halls of six communes dead for France (*mortes pour la France*) are memorials taken from OpenStreetMap, ODbL 1.0.

    Who reuses the answers credits each source and its date: see [wymmo.dev/licences](https://wymmo.dev/licences).

    For a few seconds after a restart, a route may answer 503: retry later.
    The version below is the one of this contract; its changes and the notice given before a route or a parameter is removed are told by the terms of service.
  termsOfService: https://wymmo.dev/tos
  contact:
    email: contact@wymmo.com
    url: https://wymmo.dev/contact
  version: 1.0.0
externalDocs:
  description: The service of the State this API stands in for
  url: https://geo.api.gouv.fr/decoupage-administratif
servers:
- url: https://api.wymmo.dev/geodata
tags:
- name: regions
  description: The regions, by code, name or zone
- name: departements
  description: The departements, by code, name, region or zone
- name: communes
  description: The communes, by code, name, postal code, location, departement or EPCI, with their contours
- name: epcis
  description: The intercommunal bodies (*EPCI*) with their own taxation, and their member communes
- name: communes-associees-deleguees
  description: The associated and delegated communes, former communes merged into a new one
paths:
  /regions:
    get:
      summary: Search the regions
      description: Without any criterion, the regions of mainland France and the overseas departments and regions.
      operationId: get_regions
      tags:
      - regions
      parameters:
      - $ref: '#/components/parameters/Code'
      - $ref: '#/components/parameters/Nom'
      - $ref: '#/components/parameters/Zone'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Regions'
        '400':
          description: Bad Request
        '503':
          $ref: '#/components/responses/Unavailable'
  /regions/{code}:
    get:
      summary: Get a region by its code
      operationId: get_region
      tags:
      - regions
      parameters:
      - $ref: '#/components/parameters/RegionCode'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Region'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /departements:
    get:
      summary: Search the departements
      description: Without any criterion, the departements of mainland France and the overseas departments.
      operationId: get_departements
      tags:
      - departements
      parameters:
      - $ref: '#/components/parameters/Code'
      - in: query
        name: codeRegion
        description: Code of the region of the departements
        schema:
          type: string
          example: '11'
      - $ref: '#/components/parameters/Nom'
      - $ref: '#/components/parameters/Zone'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Departements'
        '400':
          description: Bad Request
        '503':
          $ref: '#/components/responses/Unavailable'
  /departements/{code}:
    get:
      summary: Get a departement by its code
      operationId: get_departement
      tags:
      - departements
      parameters:
      - $ref: '#/components/parameters/DepartementCode'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Departement'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /communes:
    get:
      summary: Search the communes
      description: |
        Without any criterion, every commune (`type=commune-actuelle`), arrondissements municipaux excepted.
        `lat` and `lon` together find the commune whose contour holds the point.
        A list in GeoJSON, or holding the contours, needs a criterion other than `type`, `zone` and `boost`: without one, it answers 400.
      operationId: get_communes
      tags:
      - communes
      parameters:
      - $ref: '#/components/parameters/Code'
      - $ref: '#/components/parameters/CodePostal'
      - $ref: '#/components/parameters/Nom'
      - $ref: '#/components/parameters/Boost'
      - $ref: '#/components/parameters/Siren'
      - $ref: '#/components/parameters/CodeEpci'
      - $ref: '#/components/parameters/CodeDepartement'
      - $ref: '#/components/parameters/CodeRegion'
      - $ref: '#/components/parameters/CodeParent'
      - $ref: '#/components/parameters/AncienCode'
      - $ref: '#/components/parameters/Type'
      - $ref: '#/components/parameters/Zone'
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Communes'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CommuneFeatureCollection'
        '400':
          $ref: '#/components/responses/EveryContourRefused'
        '503':
          $ref: '#/components/responses/Unavailable'
  /communes/{code}:
    get:
      summary: Get a commune by its INSEE code
      operationId: get_commune
      tags:
      - communes
      parameters:
      - $ref: '#/components/parameters/CommuneCode'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Commune'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CommuneFeature'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /epcis:
    get:
      summary: Search the EPCI, the groupings of communes
      description: |
        Without any criterion, the EPCI of mainland France and the overseas departments.
        A list in GeoJSON, or holding the contours, needs a criterion other than `zone` and `boost`: without one, it answers 400.
      operationId: get_epcis
      tags:
      - epcis
      parameters:
      - $ref: '#/components/parameters/Code'
      - $ref: '#/components/parameters/Nom'
      - $ref: '#/components/parameters/Boost'
      - $ref: '#/components/parameters/CodeDepartement'
      - $ref: '#/components/parameters/CodeRegion'
      - $ref: '#/components/parameters/Zone'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Epcis'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/EpciFeatureCollection'
        '400':
          $ref: '#/components/responses/EveryContourRefused'
        '503':
          $ref: '#/components/responses/Unavailable'
  /epcis/{code}:
    get:
      summary: Get an EPCI by its SIREN code
      operationId: get_epci
      tags:
      - epcis
      parameters:
      - $ref: '#/components/parameters/EpciCode'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Epci'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/EpciFeature'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /epcis/{code}/communes:
    get:
      summary: The communes of an EPCI
      operationId: get_epci_communes
      tags:
      - epcis
      parameters:
      - $ref: '#/components/parameters/EpciCode'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Communes'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CommuneFeatureCollection'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /departements/{code}/communes:
    get:
      summary: The communes of a departement
      operationId: get_departement_communes
      tags:
      - departements
      parameters:
      - $ref: '#/components/parameters/DepartementCode'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Communes'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CommuneFeatureCollection'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /regions/{code}/departements:
    get:
      summary: Every departement of a region
      operationId: get_region_departements
      tags:
      - regions
      parameters:
      - $ref: '#/components/parameters/RegionCode'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Departements'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
  /communes_associees_deleguees:
    get:
      summary: Search the communes associées and déléguées, former communes kept inside a merged one
      description: |
        Without any criterion, every commune associée and déléguée.
        A list in GeoJSON, or holding the contours, needs a criterion other than `type`: without one, it answers 400.
      operationId: get_communes_associees_deleguees
      tags:
      - communes-associees-deleguees
      parameters:
      - $ref: '#/components/parameters/Code'
      - $ref: '#/components/parameters/Nom'
      - in: query
        name: chefLieu
        description: The INSEE code of the commune they belong to
        schema:
          type: string
          example: '01015'
      - $ref: '#/components/parameters/CodeEpci'
      - $ref: '#/components/parameters/CodeDepartement'
      - $ref: '#/components/parameters/CodeRegion'
      - $ref: '#/components/parameters/Type'
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunesAssocieesDeleguees'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CommuneAssocieeDelegueeFeatureCollection'
        '400':
          $ref: '#/components/responses/EveryContourRefused'
        '503':
          $ref: '#/components/responses/Unavailable'
  /communes_associees_deleguees/{code}:
    get:
      summary: Get a commune associée or déléguée by its INSEE code
      operationId: get_commune_associee_deleguee
      tags:
      - communes-associees-deleguees
      parameters:
      - $ref: '#/components/parameters/AssocieeDelegueeCode'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/GeometryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommuneAssocieeDeleguee'
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CommuneAssocieeDelegueeFeature'
        '404':
          description: Not Found
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  responses:
    Unavailable:
      description: Service Unavailable
    EveryContourRefused:
      description: Bad Request
      content:
        text/html; charset=utf-8:
          schema:
            type: string
            description: |
              Why a list in GeoJSON, or holding the contours, without a criterion is refused:
              the text of geo.api.gouv.fr, word for word, with its media type, `text/html`.
            example: This endpoint does not support an unfiltered API call with a geojson format output or a field with contour
  parameters:
    RegionCode:
      in: path
      name: code
      required: true
      description: The INSEE code of the region
      schema:
        type: string
        example: '75'
    DepartementCode:
      in: path
      name: code
      required: true
      description: The INSEE code of the departement
      schema:
        type: string
        example: '17'
    CommuneCode:
      in: path
      name: code
      required: true
      description: The INSEE code of the commune
      schema:
        type: string
        example: '17300'
    EpciCode:
      in: path
      name: code
      required: true
      description: The SIREN code of the EPCI
      schema:
        type: string
        example: '241700434'
    AssocieeDelegueeCode:
      in: path
      name: code
      required: true
      description: The INSEE code of the commune associée or déléguée
      schema:
        type: string
        example: '01340'
    Code:
      in: query
      name: code
      description: The INSEE code
      schema:
        type: string
    Nom:
      in: query
      name: nom
      description: A name, or the start of one, for example `rochelle`; the results then come best match first, each with its `_score`
      schema:
        type: string
    Zone:
      in: query
      name: zone
      description: Comma-separated zones among `metro`, `drom` and `com`; `metro,drom` when absent
      schema:
        type: string
        example: metro,drom
    Fields:
      in: query
      name: fields
      description: Comma-separated fields of the answer, for example `nom,code,population`; `nom` and `code` are always there
      schema:
        type: string
    CodePostal:
      in: query
      name: codePostal
      description: A postal code of the communes, five digits
      schema:
        type: string
        example: '17000'
    Boost:
      in: query
      name: boost
      description: '`population` weighs the score of a name search with the population, big communes first; any other value is ignored'
      schema:
        type: string
    Siren:
      in: query
      name: siren
      description: The SIREN code of the commune, nine digits
      schema:
        type: string
    CodeEpci:
      in: query
      name: codeEpci
      description: The SIREN code of the EPCI the communes belong to
      schema:
        type: string
    CodeDepartement:
      in: query
      name: codeDepartement
      description: The INSEE code of the departement of the results; for an EPCI, one of its departements
      schema:
        type: string
    CodeRegion:
      in: query
      name: codeRegion
      description: The INSEE code of the region of the results; for an EPCI, one of its regions
      schema:
        type: string
    CodeParent:
      in: query
      name: codeParent
      description: The commune of an arrondissement municipal, for example `75056` for Paris
      schema:
        type: string
    AncienCode:
      in: query
      name: ancienCode
      description: A former INSEE code, of a commune merged into this one
      schema:
        type: string
    Type:
      in: query
      name: type
      description: |
        Comma-separated types: `commune-actuelle` and `arrondissement-municipal` for the communes,
        `commune-associee` and `commune-deleguee` for the communes associées and déléguées.
        With `lat` and `lon`, only the first type is looked for, as the State does.
      schema:
        type: string
    Lat:
      in: query
      name: lat
      description: Latitude (WGS 84) of a point the commune holds, with `lon`
      schema:
        type: number
        format: double
    Lon:
      in: query
      name: lon
      description: Longitude (WGS 84) of a point the commune holds, with `lat`
      schema:
        type: number
        format: double
    Format:
      in: query
      name: format
      description: |
        `geojson` for a GeoJSON Feature or FeatureCollection, in `application/geo+json`, its geometries out of the properties;
        any other value, or none, for JSON.
      schema:
        type: string
    GeometryParam:
      in: query
      name: geometry
      description: |
        The geometry of the GeoJSON features: `centre`, `contour` or `bbox`, and `mairie` for the communes;
        `centre` when absent, unknown, or not served by the route.
      schema:
        type: string
    Limit:
      in: query
      name: limit
      description: The maximum number of results
      schema:
        type: integer
        format: uint32
  schemas:
    Region:
      type: object
      required:
      - nom
      - code
      properties:
        nom:
          type: string
          example: Normandie
        code:
          type: string
          example: '28'
        chefLieu:
          description: The INSEE code of the commune holding the prefecture
          type: string
          example: '76540'
        zone:
          $ref: '#/components/schemas/Zone'
        _score:
          description: How well the name matches `nom`, only when the search has one
          type: number
          format: double
    Regions:
      type: array
      items:
        $ref: '#/components/schemas/Region'
    Departement:
      type: object
      required:
      - nom
      - code
      properties:
        nom:
          type: string
          example: Eure
        code:
          type: string
          example: '27'
        codeRegion:
          type: string
          example: '28'
        chefLieu:
          description: The INSEE code of the commune holding the prefecture
          type: string
          example: '27229'
        zone:
          $ref: '#/components/schemas/Zone'
        region:
          $ref: '#/components/schemas/Region'
        _score:
          description: How well the name matches `nom`, only when the search has one
          type: number
          format: double
    Departements:
      type: array
      items:
        $ref: '#/components/schemas/Departement'
    CodeNom:
      description: The code and the name of a commune or a territory, as nested in another record
      type: object
      required:
      - code
      - nom
      properties:
        code:
          type: string
        nom:
          type: string
    Commune:
      type: object
      required:
      - nom
      - code
      properties:
        nom:
          type: string
          example: La Rochelle
        code:
          type: string
          example: '17300'
        type:
          description: '`commune-actuelle` or `arrondissement-municipal`'
          type: string
        siren:
          type: string
        codeDepartement:
          type: string
        codeRegion:
          type: string
        codeEpci:
          type: string
        codeParent:
          type: string
        codesPostaux:
          type: array
          items:
            type: string
        population:
          type: integer
          format: uint64
        anciensCodes:
          type: array
          items:
            type: string
        zone:
          $ref: '#/components/schemas/Zone'
        associees:
          type: array
          items:
            $ref: '#/components/schemas/CodeNom'
        deleguees:
          type: array
          items:
            $ref: '#/components/schemas/CodeNom'
        surface:
          description: In hectares
          type: number
          format: double
        mortePourLaFrance:
          type: boolean
        centre:
          $ref: '#/components/schemas/Geometry'
        contour:
          $ref: '#/components/schemas/Geometry'
        mairie:
          $ref: '#/components/schemas/Geometry'
        bbox:
          $ref: '#/components/schemas/Geometry'
        epci:
          $ref: '#/components/schemas/CodeNom'
        departement:
          $ref: '#/components/schemas/CodeNom'
        region:
          $ref: '#/components/schemas/CodeNom'
        _score:
          description: How well the name matches `nom`, only when the search has one
          type: number
          format: double
    Communes:
      type: array
      items:
        $ref: '#/components/schemas/Commune'
    CommuneFeature:
      type: object
      required:
      - type
      - properties
      properties:
        type:
          description: '`Feature`'
          type: string
        properties:
          $ref: '#/components/schemas/Commune'
        geometry:
          $ref: '#/components/schemas/Geometry'
    CommuneFeatureCollection:
      type: object
      required:
      - type
      - features
      properties:
        type:
          description: '`FeatureCollection`'
          type: string
        features:
          type: array
          items:
            $ref: '#/components/schemas/CommuneFeature'
    Epci:
      type: object
      required:
      - nom
      - code
      properties:
        nom:
          type: string
          example: CA de La Rochelle
        code:
          description: The SIREN code
          type: string
          example: '241700434'
        type:
          description: '`CC`, `CA`, `CU`, `METRO` or `MET69`'
          type: string
        financement:
          description: '`FPU` or `FA`'
          type: string
        codesDepartements:
          type: array
          items:
            type: string
        codesRegions:
          type: array
          items:
            type: string
        population:
          type: integer
          format: uint64
        zone:
          $ref: '#/components/schemas/Zone'
        surface:
          description: In hectares
          type: number
          format: double
        centre:
          $ref: '#/components/schemas/Geometry'
        contour:
          $ref: '#/components/schemas/Geometry'
        bbox:
          $ref: '#/components/schemas/Geometry'
        _score:
          description: How well the name matches `nom`, only when the search has one
          type: number
          format: double
    Epcis:
      type: array
      items:
        $ref: '#/components/schemas/Epci'
    EpciFeature:
      type: object
      required:
      - type
      - properties
      properties:
        type:
          description: '`Feature`'
          type: string
        properties:
          $ref: '#/components/schemas/Epci'
        geometry:
          $ref: '#/components/schemas/Geometry'
    EpciFeatureCollection:
      type: object
      required:
      - type
      - features
      properties:
        type:
          description: '`FeatureCollection`'
          type: string
        features:
          type: array
          items:
            $ref: '#/components/schemas/EpciFeature'
    CommuneAssocieeDeleguee:
      type: object
      required:
      - nom
      - code
      properties:
        nom:
          type: string
          example: Arbignieu
        code:
          type: string
          example: '01015'
        type:
          description: '`commune-associee` or `commune-deleguee`'
          type: string
        chefLieu:
          description: The INSEE code of the commune it belongs to
          type: string
        codeDepartement:
          type: string
        codeRegion:
          type: string
        codeEpci:
          type: string
        surface:
          description: In hectares
          type: number
          format: double
        centre:
          $ref: '#/components/schemas/Geometry'
        contour:
          $ref: '#/components/schemas/Geometry'
        bbox:
          $ref: '#/components/schemas/Geometry'
        epci:
          $ref: '#/components/schemas/CodeNom'
        departement:
          $ref: '#/components/schemas/CodeNom'
        region:
          $ref: '#/components/schemas/CodeNom'
        _score:
          description: How well the name matches `nom`, only when the search has one
          type: number
          format: double
    CommunesAssocieesDeleguees:
      type: array
      items:
        $ref: '#/components/schemas/CommuneAssocieeDeleguee'
    CommuneAssocieeDelegueeFeature:
      type: object
      required:
      - type
      - properties
      properties:
        type:
          description: '`Feature`'
          type: string
        properties:
          $ref: '#/components/schemas/CommuneAssocieeDeleguee'
        geometry:
          $ref: '#/components/schemas/Geometry'
    CommuneAssocieeDelegueeFeatureCollection:
      type: object
      required:
      - type
      - features
      properties:
        type:
          description: '`FeatureCollection`'
          type: string
        features:
          type: array
          items:
            $ref: '#/components/schemas/CommuneAssocieeDelegueeFeature'
    Geometry:
      description: |
        A GeoJSON geometry (RFC 7946): a Point, a Polygon or a MultiPolygon, in WGS 84 longitude and latitude.
        Written as encoded once, when the data was prepared: the coordinates are never parsed back.
      type: object
      required:
      - type
      - coordinates
      properties:
        type:
          type: string
          enum:
          - Point
          - Polygon
          - MultiPolygon
        coordinates:
          type: array
          items: {}
    Zone:
      description: Where a territory lies, mainland France (metro), overseas departments and regions (drom), or overseas collectivities (com)
      type: string
      enum:
      - metro
      - drom
      - com
