openapi: 3.1.0
components:
  schemas:
    Area:
      type: object
      properties:
        enclosingCircle:
          type: object
          properties:
            center:
              type: object
              properties:
                lat:
                  type: number
                lon:
                  type: number
            radius:
              type: number
        boundingBox:
          type: object
          properties:
            lowerCorner:
              type: object
              properties:
                lat:
                  type: number
                lon:
                  type: number
            upperCorner:
              type: object
              properties:
                lat:
                  type: number
                lon:
                  type: number
    Circle:
      type: object
      properties:
        center:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
        radius:
          type: number
    DatePeriod:
      type: object
      properties:
        beginDate:
          type: string
        endDate:
          type: string
    Envelope:
      type: object
      properties:
        lowerCorner:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
        upperCorner:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
    GufCriteriaSet:
      type: object
      required:
        - area
      properties:
        deliveryAccountableParty:
          type: string
        qualityRegime:
          type: string
          enum:
            - IMBRO
            - IMBRO_A
        registrationPeriod:
          type: object
          properties:
            beginDate:
              type: string
            endDate:
              type: string
        correctionPeriod:
          type: object
          properties:
            beginDate:
              type: string
            endDate:
              type: string
        underReview:
          type: string
          enum:
            - JA
            - NEE
        area:
          type: object
          properties:
            enclosingCircle:
              type: object
              properties:
                center:
                  type: object
                  properties:
                    lat:
                      type: number
                    lon:
                      type: number
                radius:
                  type: number
            boundingBox:
              type: object
              properties:
                lowerCorner:
                  type: object
                  properties:
                    lat:
                      type: number
                    lon:
                      type: number
                upperCorner:
                  type: object
                  properties:
                    lat:
                      type: number
                    lon:
                      type: number
        startPeriod:
          type: object
          properties:
            beginDate:
              type: string
            endDate:
              type: string
        endPeriod:
          type: object
          properties:
            beginDate:
              type: string
            endDate:
              type: string
        identificationLicence:
          type: string
        legalType:
          type: string
        primaryUsageType:
          type: array
          items:
            type: string
        designInstallationFunction:
          type: string
        realisedInstallationFunction:
          type: string
    Point:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number
    QualityRegime:
      type: string
      enum:
        - IMBRO
        - IMBRO_A
    ServiceError:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        errorCode:
          type: integer
          format: int32
    YesNoEnumeration:
      type: string
      enum:
        - JA
        - NEE
  examples:
    SIMPLE_CRITERIA:
      value: |-
        {
          "startPeriod": {
            "beginDate": "2015-12-30",
            "endDate": "2016-02-01"
          },
          "endPeriod": {
            "beginDate": "2023-01-01",
            "endDate": "2024-01-01"
          },
          "identificationLicence": "identificatie beschikking-melding_IBM_01_NEW_02",
          "legalType": "beschikking",
          "primaryUsageType": [
            "openbareDrinkwatervoorziening"
          ],
          "designInstallationFunction": "onttrekking",
          "realisedInstallationFunction": "onttrekking",
          "area": {
            "enclosingCircle": {
              "center": {
                "lat": 52.038297852,
                "lon": 5.31447958948
              },
              "radius": 10
            }
          }
        }
paths:
  /gu/guf/v1/bro-ids:
    get:
      summary: Lijst van GUF BRO-IDs
      description: Haalt de lijst van GUF bro-ids op waarvoor [bronhouder](https://basisregistratieondergrond.nl/service-contact/formulieren/aangemeld-bro/) verantwoordelijk is.
      operationId: bro-ids
      parameters:
        - description: Het kvk (kamer van koophandel) nummer van een GUF bronhouder
          example: '12345678'
          name: bronhouder
          in: query
          schema:
            type: string
          required: true
        - description: Registered is een optionele parameter, bij afwezigheid geeft deze methode alle GUF BRO-IDs terug onafhankelijk of die wel/niet uit registratie zijn genomen. <BR>registered = ja geeft alleen BRO-IDs terug die in registratie zijn genomen. <BR>registered = nee geeft alleen BRO-IDs terug die uit registratie zijn genomen.
          name: registered
          in: query
          schema:
            type: string
      responses:
        '200':
          description: De Lijst van GUF BRO-IDs voor dit registratie object type waarvoor bronhouder verantwoordelijk is.
          headers:
            API-Version:
              description: Versie van deze GUF API
              schema:
                type: string
                examples:
                  - 3.2.1
          content:
            application/json: {}
        '400':
          description: Er bevinden zich andere fouten in het GUF verzoek.
          headers:
            API-Version:
              description: Versie van deze GUF API
              schema:
                type: string
                examples:
                  - 3.2.1
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  description:
                    type: string
                  errorCode:
                    type: integer
                    format: int32
  /gu/guf/v1/characteristics/searches:
    post:
      summary: Haalt de karakteristieken op van een set van registratie objecten, gegeven een kenmerkenverzameling (kenset).
      description: 'De karakteristieken geven een samenvatting van een object zodat een verdere selectie gemaakt kan worden. Het past in een twee-traps-benadering, waarbij de eerste stap bestaat uit het ophalen van de karakteristieken en de 2e stap uit het ophalen van de gewenste registratie objecten. Het resultaat van deze operatie is gemaximaliseerd op 2000. Merk op: deze service leent zich niet voor "tiling" (binair geografisch zoeken). voor meer info.'
      operationId: characteristics
      parameters:
        - content:
            text/plain:
              schema:
                type: string
          description: Een optionele GUF referentie van de gebruiker. "-" wordt aangenomen bij afwezigheid.
          name: requestReference
          in: query
      requestBody:
        description: 'De set van kenmerken. Zie voor meer informatie: https://www.bro-productomgeving.nl/bpo/latest/'
        content:
          application/json:
            examples:
              Simple Criteria:
                value: |-
                  {
                    "startPeriod": {
                      "beginDate": "2015-12-30",
                      "endDate": "2016-02-01"
                    },
                    "endPeriod": {
                      "beginDate": "2023-01-01",
                      "endDate": "2024-01-01"
                    },
                    "identificationLicence": "identificatie beschikking-melding_IBM_01_NEW_02",
                    "legalType": "beschikking",
                    "primaryUsageType": [
                      "openbareDrinkwatervoorziening"
                    ],
                    "designInstallationFunction": "onttrekking",
                    "realisedInstallationFunction": "onttrekking",
                    "area": {
                      "enclosingCircle": {
                        "center": {
                          "lat": 52.038297852,
                          "lon": 5.31447958948
                        },
                        "radius": 10
                      }
                    }
                  }
            schema:
              type: object
              required:
                - area
              properties:
                deliveryAccountableParty:
                  type: string
                qualityRegime:
                  type: string
                  enum:
                    - IMBRO
                    - IMBRO_A
                registrationPeriod:
                  type: object
                  properties:
                    beginDate:
                      type: string
                    endDate:
                      type: string
                correctionPeriod:
                  type: object
                  properties:
                    beginDate:
                      type: string
                    endDate:
                      type: string
                underReview:
                  type: string
                  enum:
                    - JA
                    - NEE
                area:
                  type: object
                  properties:
                    enclosingCircle:
                      type: object
                      properties:
                        center:
                          type: object
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                        radius:
                          type: number
                    boundingBox:
                      type: object
                      properties:
                        lowerCorner:
                          type: object
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                        upperCorner:
                          type: object
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                startPeriod:
                  type: object
                  properties:
                    beginDate:
                      type: string
                    endDate:
                      type: string
                endPeriod:
                  type: object
                  properties:
                    beginDate:
                      type: string
                    endDate:
                      type: string
                identificationLicence:
                  type: string
                legalType:
                  type: string
                primaryUsageType:
                  type: array
                  items:
                    type: string
                designInstallationFunction:
                  type: string
                realisedInstallationFunction:
                  type: string
        required: true
      responses:
        '200':
          description: De set van GUF karakteristieken die matched met de criteria dan wel een afwijzing.
          headers:
            API-Version:
              description: Versie van deze GUF API
              schema:
                type: string
                examples:
                  - 3.2.1
          content:
            application/xml: {}
        '400':
          description: Er bevinden zich andere fouten in het GUF verzoek.
          headers:
            API-Version:
              description: Versie van deze GUF API
              schema:
                type: string
                examples:
                  - 3.2.1
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  description:
                    type: string
                  errorCode:
                    type: integer
                    format: int32
  /gu/guf/v1/objects/{broId}:
    get:
      summary: Haalt een grondwatergebruiksysteem (groundwater usage facility, GUF) op op basis van een BRO-ID
      description: Haal een grondwatergebruiksysteem op op basis van een BRO-ID. De operatie retourneert een object op basis van het BRO-ID als een 'O' (actuele situatie), of 'DO' (uit registratie) als IMBRO XML. De andere variant 'O-DP' is niet ondersteund omdat hier authenticatie / autorisatie voor nodig is (er worden bronhouder gevoelige gegevens terug gegeven). Gebruik hiervoor de 'DigiKoppeling' webservice. Zie [hier](https://www.bro-productomgeving.nl/bpo/latest/grondwatergebruik/grondwatergebruiksysteem-guf/guf-berichtencatalogus-uitgiftewebservice) voor meer info.
      operationId: objects
      parameters:
        - content:
            text/plain:
              schema:
                type: string
          description: Het BRO-ID van het GUF object.
          name: broId
          in: path
          required: true
        - allowEmptyValue: true
          description: Aanwezigheid van deze parameter geeft volledige geschiedenis terug. Afwezigheid de actuele situatie.
          example: ja
          name: fullHistory
          in: query
          schema:
            type: string
        - description: Een optionele GUF referentie van de gebruiker. "-" wordt aangenomen bij afwezigheid.
          example: MijnGUF--object-aanvraag-000001
          name: requestReference
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Het aangevraagde registratie object dan wel een afwijzing van het GUF verzoek.
          headers:
            API-Version:
              description: Versie van deze GUF API
              schema:
                type: string
                examples:
                  - 3.2.1
          content:
            application/xml: {}
        '400':
          description: Er bevinden zich andere fouten in het GUF verzoek.
          headers:
            API-Version:
              description: Versie van deze GUF API
              schema:
                type: string
                examples:
                  - 3.2.1
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  description:
                    type: string
                  errorCode:
                    type: integer
                    format: int32
info:
  title: Grondwatergebruiksysteem (GUF)
  version: 2.197.0
  description: Landelijke Voorziening Basisregistratie Ondergrond (BRO), uitgifte en validatie Grondwatergebruiksysteem (GUF).
  contact:
    name: BRO Servicedesk
    email: support@broservicedesk.nl
    url: https://basisregistratieondergrond.nl/service-contact/
