components:
  schemas:
    FullCustomDownloadRequest:
      properties:
        featuretypes:
          items:
            enum:
            - functioneelgebied
            - gebouw
            - geografischgebied
            - hoogte
            - inrichtingselement
            - plaats
            - registratiefgebied
            - relief
            - spoorbaandeel
            - terrein
            - waterdeel
            - wegdeel
            type: string
          minItems: 1
          type: array
          uniqueItems: true
        format:
          enum:
          - gml
          type: string
        geofilter:
          type: string
      required:
      - format
      - featuretypes
      type: object
    HalLink:
      properties:
        href:
          type: string
        rel:
          type: string
        type:
          type: string
      required:
      - href
      type: object
    timeliness:
      properties:
        datetimeTo:
          readOnly: true
          type: string
        featuretype:
          enum:
          - functioneelgebied
          - gebouw
          - geografischgebied
          - hoogte
          - inrichtingselement
          - plaats
          - registratiefgebied
          - relief
          - spoorbaandeel
          - terrein
          - waterdeel
          - wegdeel
          readOnly: true
          type: string
      type: object
info:
  description: |
    TOP250NL is een digitaal objectgericht topografisch bestand wat ten grondslag ligt aan de topografische kaartseries 1:250.000 en wat veelvuldig in diverse GIS- en CAD-systemen wordt gebruikt als ondergrond.
    Met deze API is het mogelijk om gegevens uit de BRT dataset te downloaden. Deze BRT-gegevens zijn te downloaden voor gebruik in eigen GIS-software. De BRT-gegevens zijn als extract in GML-formaat te downloaden.
    Dit document bevat alleen informatie m.b.t. het gebruik van deze API. De BRT-modeldocumentatie met bijbehorend schema(xsd) en beschrijvingen van de download formaten kun je vinden op: https://register.geostandaarden.nl/?url=brt/index.html.
    Hieronder worden eerst een aantal algemene begrippen en concepten uitgelegd. Vervolgens wordt elk endpoint individueel beschreven.

    Een stappenplan voor het downloaden via deze API staat [hier](https://www.pdok.nl/documents/1901824/4016976/Stappenplan_PDOK_download_APIs.pdf) beschreven.
  title: TOP250NL Download API
  version: v1
openapi: 3.0.0
paths:
  /dataset:
    get:
      operationId: GetDataset
      responses:
        "200":
          content:
            application/json:
              example:
                timeliness:
                - datetimeTo: "2021-01-26T00:00:00Z"
                  featuretype: functioneelgebied
                - datetimeTo: "2021-01-26T00:00:00Z"
                  featuretype: gebouw
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: geografischgebied
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: hoogte
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: inrichtingselement
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: plaats
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: registratiefgebied
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: relief
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: spoorbaandeel
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: terrein
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: waterdeel
                - datetimeTo: "2021-01-01T00:00:00Z"
                  featuretype: wegdeel
              schema:
                properties:
                  timeliness:
                    description: |
                      Lijst met actualiteit per featuretype. Het datum tijd formaat is ISO 8601 en altijd in UTC.
                    items:
                      $ref: '#/components/schemas/timeliness'
                    type: array
                required:
                - timeliness
                type: object
          description: OK
        "500":
          description: Interne server fout
      summary: Dit endpoint voorziet in metadata over de TOP250NL dataset downloads
      tags:
      - Dataset
  /full/custom:
    options:
      operationId: FullCustomDownloadCORS
      responses:
        "204":
          description: Standaard response
      summary: De OPTIONS methode is beschikbaar voor de CORS preflight check
      tags:
      - Full Custom
    post:
      operationId: FullCustomDownload
      requestBody:
        content:
          application/json:
            example:
              featuretypes:
              - functioneelgebied
              - gebouw
              - geografischgebied
              - hoogte
              - inrichtingselement
              - plaats
              - registratiefgebied
              - relief
              - spoorbaandeel
              - terrein
              - waterdeel
              - wegdeel
              format: gml
              geofilter: POLYGON((211417.92 475752.4800000001,212390.64000000004 475896.12,212916.48000000004
                475818.84,212879.52000000005 475360.2,212950.08000000002 475203.12,212839.2
                475065.36,212819.04 474981.36,212819.04 474877.2,212772 474857.04,212792.16
                474769.68,212832.48 474705.84,212889.6 474695.76,213010.56000000003
                474685.68,213044.16 474611.76,213030.72 474450.48,212637.6 474423.6,212708.16
                473956.56,211122.24000000002 473849.04,210453.6 473896.08,210315.84000000003
                473970,211417.92 475752.4800000001))
            schema:
              $ref: '#/components/schemas/FullCustomDownloadRequest'
        description: JSON object waarin staat gespecificeerd welke informatie de download
          moet bevatten
        required: true
      responses:
        "202":
          content:
            application/json:
              example:
                _links:
                  status:
                    href: /brt/top250nl/api/v1_0/full/custom/09bf3690-e0a1-43cc-7550-f689936d374d/status
                downloadRequestId: 09bf3690-e0a1-43cc-7550-f689936d374d
              schema:
                properties:
                  _links:
                    properties:
                      status:
                        allOf:
                        - $ref: '#/components/schemas/HalLink'
                        description: Absolute path naar het endpoint waarop de status
                          van de aanvraag opgehaald kan worden
                    type: object
                  downloadRequestId:
                    description: ID van het gemaakte download request
                    type: string
                required:
                - downloadRequestId
                - _links
                type: object
          description: |
            Verzoek geaccepteerd
        "500":
          description: Interne server fout
      summary: Met dit endpoint kan een full custom download aangevraagd worden
      tags:
      - Full Custom
  /full/custom/{downloadRequestId}/status:
    get:
      operationId: FullCustomDownloadStatus
      parameters:
      - in: path
        name: downloadRequestId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              example:
                _links:
                  self:
                    href: /brt/top250nl/api/v1_0/full/custom/09bf3690-e0a1-43cc-7550-f689936d374d/status
                progress: 23
                status: RUNNING
              schema:
                properties:
                  _links:
                    properties:
                      self:
                        allOf:
                        - $ref: '#/components/schemas/HalLink'
                        description: Absolute path naar het endpoint waarop de status
                          van de aanvraag opgehaald kan worden
                    type: object
                  progress:
                    type: integer
                  status:
                    enum:
                    - PENDING
                    - RUNNING
                    type: string
                required:
                - status
                - progress
                - _links
                type: object
          description: Full custom download nog niet gereed
        "201":
          content:
            application/json:
              example:
                _links:
                  download:
                    href: /brt/top250nl/api/v1_0/extract/72f0d5d6-d34c-439b-a115-b53811aa8a72/extract.zip
                progress: 100
                status: COMPLETED
              schema:
                properties:
                  _links:
                    properties:
                      download:
                        allOf:
                        - $ref: '#/components/schemas/HalLink'
                        description: Absolute path waarop het bestand gedownload kan
                          worden
                    type: object
                  progress:
                    type: integer
                  status:
                    enum:
                    - COMPLETED
                    type: string
                required:
                - status
                - progress
                - _links
                type: object
          description: Het bestand is gereed om te downloaden
        "404":
          description: Full custom download request met het gegeven ID is niet bij
            ons bekend
        "429":
          description: Te veel requests in korte tijd voor gegeven ID
        "500":
          content:
            application/json:
              example:
                progress: 100
                reason: Failed to generate download
                status: FAILED
              schema:
                properties:
                  progress:
                    type: integer
                  reason:
                    type: string
                  status:
                    type: string
                type: object
          description: Interne server fout
      summary: Dit endpoint geeft de status terug van een aangevraagde full custom
        download
      tags:
      - Full Custom
  /full/predefined/top250nl-gml-nl-nohist.zip:
    get:
      operationId: GetFullPredefinedGmlNl
      responses:
        "307":
          description: Redirect
          headers:
            Location:
              description: Absolute path waarop het bestand gedownload kan worden
        "404":
          description: Not found
      summary: |
        Met dit endpoint kan een full download gestart worden waarbij geen filters zijn toegepast op type feature of gebied
      tags:
      - Full Predefined
  /health-download:
    get:
      operationId: healthDownload
      responses:
        "200":
          description: Check succesvol
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
      summary: |
        Voor intern-PDOK gebruik: Met dit endpoint kan een test download aangemaakt worden voor het testen van de downloadservices.
      tags:
      - Health check
servers:
- url: https://api.pdok.nl/brt/top250nl/download/v1_0
