correct different postal code types

correct different postal code types

#%RAML 1.0
---
title: Postal Code API
baseUri: https://api.bring.com/pickuppoint/api

documentation:
- title: Introduction
  content: |
      With the Postal Code API you can

      * validate a postal code
      * look up the city of a postal code
      * get the postal code type, e.g. normal or P.O. Box (for Norway)
      * list all valid postal codes for supported countries (Norway, Sweden, Denmark and Finland)

      The API has two interfaces: XML and JSON.

- title: Authentication
  content: |
      To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

- title: Supported Countries
  content: |
      The following countries are supported:

      * NO - Norway
      * DK - Denmark
      * SE - Sweden
      * FI - Finland
      * NL - Netherlands
      * DE - Germany
      * US - United States
      * BE - Belgium
      * FO - Faroe Islands
      * GL - Greenland

      The service uses [GeoNames](http://www.geonames.org/) as source for most countries except Norway.

      For unsupported countries (countries not in the list above), all postal codes will be marked as valid with no city name returned. In these cases it is recommended to prompt the user to input the city name themselves.

      For countries that have multiple results (cities) for a given postal code, a list of cities will be returned. See example below.

      ### Postal Code type for Norway

      For Norway, you also get information about the postal code type. This is set in the `postalCodeType` in the response:

      | `postalCodeType` | Description |
      |:-----------------|:------------|
      | NORMAL | Normal postal code suitable for delivering packages. Contains street addresses or mix of street and other postal code types. |
      | PO_BOX | Postal code contains only P.O. Box addresses. Only certain Bring services can be delivered to these addresses (see the [Shipping Guide](/api/shipping-guide_2/)). |
      | SPECIAL_CUSTOMER | Special, e.g special return postal codes for selected customers. |
      | UNKNOWN | Unknown postal code type. Used for e.g. international postal codes. |

- title: Support CORS
  content: |

      CORS headers will be added to response only for authenticated requests.

/postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: 1337
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: SE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.xml

/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code having Multiple Cities

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: '01156'
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code having Multiple Cities
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.xml

/postalCode/{countryCode}/getAllValidPostalCodes{mediaTypeExtension}:
  displayName: Lookup all postal codes for Norway, Sweden, Denmark or Finland

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes for Norway, Sweden, Denmark or Finland
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.xml

/postalCode/{countryCode}/allValidPostalCodesDetails{mediaTypeExtension}:
  displayName: Lookup all postal codes with details for Norway, Sweden, Denmark or Finland

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes with details for Norway, Sweden, Denmark or Finland
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.xml

#%RAML 1.0
---
title: Postal Code API
baseUri: https://api.bring.com/pickuppoint/api

documentation:
- title: Introduction
  content: |
      With the Postal Code API you can

      * validate a postal code
      * look up the city of a postal code
      * get the postal code type, e.g. normal or P.O. Box (for Norway)
      * list all valid postal codes for supported countries (Norway, Sweden, Denmark and Finland)

      The API has two interfaces: XML and JSON.

- title: Authentication
  content: |
      To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

- title: Supported Countries
  content: |
      The following countries are supported:

      * NO - Norway
      * DK - Denmark
      * SE - Sweden
      * FI - Finland
      * NL - Netherlands
      * DE - Germany
      * US - United States
      * BE - Belgium
      * FO - Faroe Islands
      * GL - Greenland

      The service uses [GeoNames](http://www.geonames.org/) as source for most countries except Norway.

      For unsupported countries (countries not in the list above), all postal codes will be marked as valid with no city name returned. In these cases it is recommended to prompt the user to input the city name themselves.

      For countries that have multiple results (cities) for a given postal code, a list of cities will be returned. See example below.

      ### Postal Code type for Norway

      For Norway, you also get information about the postal code type. This is set in the `postalCodeType` in the response:

      | `postalCodeType` | Description |
      |:-----------------|:------------|
      | NORMAL | Normal postal code suitable for delivering packages. Contains street addresses or mix of street and other postal code types. |
      | POBOX | Postal code contains only P.O. Box addresses. Only certain Bring services can be delivered to these addresses (see the [Shipping Guide](/api/shipping-guide_2/)). |
      | SPECIALCUSTOMER | Special, e.g special return postal codes for selected customers. |
      | SPECIALNOSTREET | Special, e.g special postal codes for customers with old "serviceboks". |
      | UNKNOWN | Unknown postal code type. Used for e.g. international postal codes. |

- title: Support CORS
  content: |

      CORS headers will be added to response only for authenticated requests.

/postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: 1337
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: SE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.xml

/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code having Multiple Cities

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: '01156'
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code having Multiple Cities
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.xml

/postalCode/{countryCode}/getAllValidPostalCodes{mediaTypeExtension}:
  displayName: Lookup all postal codes for Norway, Sweden, Denmark or Finland

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes for Norway, Sweden, Denmark or Finland
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.xml

/postalCode/{countryCode}/allValidPostalCodesDetails{mediaTypeExtension}:
  displayName: Lookup all postal codes with details for Norway, Sweden, Denmark or Finland

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes with details for Norway, Sweden, Denmark or Finland
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.xml


Group pickup point 200 examples

Group pickup point 200 examples

#%RAML 1.0
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      ### Rate limiting

      The Pickup point API had a rate limit, primarily considered on a per-user basis.

      Since the Pickup Point API became authenticated from 01.11.2020, it is mandatory to be authenticated.

      There will be no rate limiting once you authenticate yourself before calling Pickuppoint API.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 34 : Manned

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      The Pickup Point API requires authentication. To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.json
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.json
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.json
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.json
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.json
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
          application/xml:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.xml
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.xml
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.xml
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.xml
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.xml
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.json
          application/xml:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.json
          application/xml:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.xml

#%RAML 1.0
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      ### Rate limiting

      The Pickup point API had a rate limit, primarily considered on a per-user basis.

      Since the Pickup Point API became authenticated from 01.11.2020, it is mandatory to be authenticated.

      There will be no rate limiting once you authenticate yourself before calling Pickuppoint API.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 34 : Manned

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      The Pickup Point API requires authentication. To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        description: |
          Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
        body:
          application/json:
            examples:
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.json
          application/xml:
            examples:
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        description: |
          If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
        body:
          application/json:
            examples:
              specific_string:
                displayName: Find pickup points containing a specific string
                value: !include examples/filter_search.json
          application/xml:
            examples:
              specific_string:
                displayName: Find pickup points containing a specific string
                value: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        description: |
          If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

          - `ALL_WEEKDAYS` (default)
          - `MONDAY`
          - `TUESDAY`
          - `WEDNESDAY`
          - `THURSDAY`
          - `FRIDAY`
          - `SATURDAY`
          - `SUNDAY`

          If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
        body:
          application/json:
            examples:
              specific_days:
                displayName: Find pickup points containing a specific string
                value: !include examples/filter_days.json
          application/xml:
            examples:
              specific_days:
                displayName: Find pickup points containing a specific string
                value: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        description: |
          If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

          The format of `<time>` is `HHmm`.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
        body:
          application/json:
            examples:
              specific_hours:
                displayName: Find pickup points open at specific hours
                value: !include examples/filter_hours.json
          application/xml:
            examples:
              specific_hours:
                displayName: Find pickup points open at specific hours
                value: !include examples/filter_hours.xml

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.json
          application/xml:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.json
          application/xml:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.xml


adding head/options/put http methods

adding head/options/put http methods

#%RAML 0.8
---
title: Example REST API
documentation:
    - title: Home
      content: |
        Welcome to the example API.
baseUri: http://{host}:{port}/{version}
version: v1
mediaType: application/json
protocols: [HTTP, HTTPS]
securitySchemes:
    - x_token_auth:
        description: Authorization header token policy
        type: x-ApiKey
    - x_ticket_auth:
        description: Standard Pyramid Auth Ticket policy
        type: x-Ticket
        settings:
            secret: auth_tkt_secret
            hashalg: sha512
            cookie_name: ramses_auth_tkt
            http_only: 'true'
    - read_only_users:
        description: ACL that allows authenticated users to read collection
        type: x-ACL
        settings:
            collection: |
                allow admin all
                allow authenticated get
            item: |
                allow admin all
                allow authenticated get
    - read_only_useritem_everyone:
        description: ACL that allows everyone to read item, authenticated users to read collection
        type: x-ACL
        settings:
            collection: |
                allow admin all
                allow authenticated get
            item: |
                allow admin all
                allow everyone get
                allow {{user_self}} patch
securedBy: [x_ticket_auth]

/stories:
    securedBy: [read_only_users]
    displayName: All stories
    get:
        description: Get all stories
    post:
        description: Create a new story
        body:
            application/json:
                schema: !include schemas/story.json
    patch:
        description: Update multiple stories
    delete:
        description: Delete multiple stories
    head:
        description: Determine whether a given resource is available
    options:
        description: Retrieve the available HTTP verbs for a given resource

    /{id}:
        displayName: One story
        get:
            description: Get a particular story
        delete:
            description: Delete a particular story
        patch:
        put:
            description: Update a particular story
        head:
            description: Determine whether a given resource is available
        options:
            description: Retrieve the available HTTP verbs for a given resource

/users:
    securedBy: [read_only_useritem_everyone]
    displayName: All users
    get:
        description: Get all users
    post:
        description: Create a new user
        body:
            application/json:
                schema: !include schemas/user.json
    head:
        description: Determine whether a given resource is available
    options:
        description: Retrieve the available HTTP verbs for a given resource

    /{username}:
        displayName: One user
        get:
            description: Get a particular user
        patch:
        put:
            description: Update a particular user
        delete:
            description: Delete a particular user

        /settings:
            displayName: User settings
            get:
                description: Get all settings of a particular user
            post:
                description: Change a user's settings

        /groups:
            displayName: User groups
            get:
                description: Get all groups of a particular user
            post:
                description: Change a user's groups

        /profile:
            displayName: User profile
            get:
                description: Get a user's profile
            post:
                description: Create a user's profile
                body:
                    application/json:
                        schema: !include schemas/profile.json
            patch:
                description: Update a user's profile

#%RAML 0.8
---
title: Example REST API
documentation:
    - title: Home
      content: |
        Welcome to the example API.
baseUri: http://{host}:{port}/{version}
version: v1
mediaType: application/json
protocols: [HTTP, HTTPS]
securitySchemes:
    - x_token_auth:
        description: Authorization header token policy
        type: x-ApiKey
    - x_ticket_auth:
        description: Standard Pyramid Auth Ticket policy
        type: x-Ticket
        settings:
            secret: auth_tkt_secret
            hashalg: sha512
            cookie_name: ramses_auth_tkt
            http_only: 'true'
    - read_only_users:
        description: ACL that allows authenticated users to read collection
        type: x-ACL
        settings:
            collection: |
                allow admin all
                allow authenticated get
            item: |
                allow admin all
                allow authenticated get
    - read_only_useritem_everyone:
        description: ACL that allows everyone to read item, authenticated users to read collection
        type: x-ACL
        settings:
            collection: |
                allow admin all
                allow authenticated get
            item: |
                allow admin all
                allow everyone get
                allow {{user_self}} patch
securedBy: [x_ticket_auth]

/stories:
    securedBy: [read_only_users]
    displayName: All stories
    get:
        description: Get all stories
    post:
        description: Create a new story
        body:
            application/json:
                schema: !include schemas/story.json
    patch:
        description: Update multiple stories
    delete:
        description: delete multiple stories

    /{id}:
        displayName: One story
        get:
            description: Get a particular story
        delete:
            description: Delete a particular story
        patch:
            description: Update a particular story

/users:
    securedBy: [read_only_useritem_everyone]
    displayName: All users
    get:
        description: Get all users
    post:
        description: Create a new user
        body:
            application/json:
                schema: !include schemas/user.json

    /{username}:
        displayName: One user
        get:
            description: Get a particular user
        patch:
            description: Update a particular user
        delete:
            description: Delete a particular user

        /settings:
            displayName: User settings
            get:
                description: Get all settings of a particular user
            post:
                description: Change a user's settings

        /groups:
            displayName: User groups
            get:
                description: Get all groups of a particular user
            post:
                description: Change a user's groups

        /profile:
            displayName: User profile
            get:
                description: Get a user's profile
            post:
                description: Create a user's profile
                body:
                    application/json:
                        schema: !include schemas/profile.json
            patch:
                description: Update a user's profile


cleanup

cleanup

Removed commented-out section that is no longer needed.

#%RAML 1.0 Library

# Name: dd-base-types.raml
#
# Date: 2018-07-17
#
#  This file defines the basic datatypes used in the DD API and DD-OPER API.

types:
  AdditionalQuality:
    type: integer
    description: Provides detailed information on specific Quality numbers.

  Altitude: number

  Aspect:
    description: A matematical derived variant of a specific measurement, forecast, etc.
    type: object
    properties:
      name: string
      unit: string

  AspectSet:
    description: The AspectSet defines a group of related mathematical values for a single measurement, forecast, etc
    type: object
    properties:
      name: AspectSetName
      aspects:
        type: Aspect[]
        minItems: 0

  AspectSetName:
    description:
    type: string
    default: "standard"
    example: "minimum, maximum, standard, ...."

  AspectPointsValue:
    description: Object used for Event.Aspect.Points. Specifies the values in points array in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      points: PointsValue[]

  AspectValue:
    description: Object used for Event.Aspect[] results. Specifies the value in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      value: number
      quality?: number
      additionalQuality?: number

# BB is not required as object since bbox is only used as query parameter (toch maar laten staan? SH)
  BoundingBox:
    description: The specification of a bounding box using the longitude and latitiude of the most SouthWest point followed by the most NorthEast points (GeoJSON).
    type: Double[]
    minItems: 4
    maxItems: 4
    examples:
      -bbox: [ 4.123456, 52.123456, 10.123456, 55.123456 ]

  Coordinate:
    type: number
    format: double

  Double:
    description: A value of type Double (todo specify #digits/format?).
    type: number
    format: double

  EndTime:
    type: datetime
    example: 2018-01-01T00:00:00Z
    description:  The End date/time of the timeseries, or the End date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.
      The endtime is exlusive, hence the requested period ends just before the given time.
      2018-01-01T00:00:00Z - 2018-01-01T00:00:10Z  specifies a 10 minute period starting at midnight and
      ending at 2018-01-01T00:09:59.99999Z

  Event:
    description: In case of scalar time series the event contains time stamp and value, optionally extended with
      an interval specification (startTime/endTime/resultTime), and a quality indication (quality, additionalQuality).
      In case of a timeseries with Aspects or with values on multiple points, the events contains object for the aspects or points.
    type: object
    properties:
      timeStamp?: datetime
      startTime?: StartTime
      endTime?: EndTime
      resultTime?: datetime
      value?:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: number
      quality?:
        description: See value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number
      aspects?:
        type: AspectValue[] | AspectPointsValue []
        description: When Aspects are used the value/quality/unit are given in and object for each aspect or aspect+point.
      points?:
        type: PointsValue[]
        description: When multiple positions are involved the value/quantity/unit are given in context of each position.

  FilterError:
    type: object
    description: Defines the field of an error in the filtering syntax.
    properties:
      errorType: string
      context: string

  Geometry:
    description: A geometry in GeoJSON format. Digital Delta currently only supports the Point and MultiPoint types.
    type: object
    properties:
      type:
        description: The geometry type. Must have the value "Point" or "MultiPoint".
        type: string
        example: "Point"
      coordinates?:
        description: An array of doubles, representing a Longitude, Latitude and optional Altitude.
        type: Position | Positions
        examples:
          -point:  [4.234 , 5.23423]
          -multipoint:  [[4.2, 52.0], [3.2, 52.3,0]]

  Identifier:
    type: string | Uuid
    description: An uuid or a preferably human readable identifier.

  Institution:
    type: object
    properties:
      name:
        type: string
        description: The name of the institution that produced and/or owns the data
      description?:
        type: string
        description: Additional discription of the institution

# IntervalLength is not required as object since it is only used as query parameter (toch maar laten staan? SH)
  IntervalLength:
    default: 10min

  Location:
    description: Generic DD API 2.0 Location object structure that is used by /dd and /dd-oper. Most attributes are optional as the content returned in the response depends on the request.  Location attributes are placed within the properties group of the GeoJSON  object.
    properties:
      type:
        description: Type of GeoJSON object. In the DD-API the only allowed type is "Feature"
        type: string
        enum: ["Feature"]
      geometry:
        description: The coordinate(s) of the Location are placed within the "geometry" section of the GeoJSON object. DD-API uses Point and Multi-Point locations, but is not restricted to these two.
        type: Geometry | nil
      properties?:
        description: The attributes of Location object are placed within the properties group of the GeoJSON object.
        type: object
        properties:
          node?: Node
          url?: string
          locationId?: string
          locationCode?: string
          referenceLevel?:
            description: GeoJSON element. Specifies the reference plane for the altitude coordinates (third). For example "NAP"
            type: string
          crs?:
            description: GeoJSON element. According to GeoJSON the coordinate reference system element is only included when it is not "WGS84" (default).
            type: string
          locationName?: LocationName
          locationNameSpace?:
            type: LocationNameSpace
          displayNameDetail?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameGlobal?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameSpace?:
            type: LocationNameSpace
            description: Remark, Only used in dd-oper response.
          parentName?:
            type: LocationName
            description: Remark, Only used in dd-oper response.

  LocationName:
    type: string
    example: "Hoek-van-Holland"

  LocationNameSpace:
    type: string
    example: "NL.RWS.WM"

  Node:
    description: Node objects contain the properties of the data node. A node is an operational implementation of the Digital Delta specification.
    type: object
    properties:
      id?:
        type: Identifier
      name:
        type: string
        description: The name of the node.<br/>
      description?:
        type: string
        description: The description of the node.
      baseUrl?:
        type: string
        description: The base URL of the node.

  ObservationType:
    description: Generic DD API 2.0 parameter object. DD-OPER API response returns a subset of the attributes.
    type: object
    properties:
      node?: Node
      url?: Url
      id?: Identifier
      quantityName?:
        description: Composed name of the quantity(.parameterCode) that was measured or computed.
          Remark Only used in dd-oper response.
        type: QuantityName
      parameterCode?:
        description: Parameter code specifying the observationtype. Non-biological observation types follow the Aquo standards.
        type: string
      description?: string
      quantity?: string
      unit?: string
      compartment?:
        description: The compartment in which the measurement/computationt is available. Standardised Aquo compartments.
        type: string
        example:  OW, DL, GW, LW
      aspectSet?:
        description: Optional, currently only provided and used by RWS.
        type: AspectSet

  PageLinks:
    description: The object contains urls and page size information to support back and forward paging
    type: object
    properties:
      totalObjectCount?:
        description: The actual number of objects available. When paging is used the response contains a subset of the total obejcts available up to the max page size.
        type: integer
      maxPageSize?:
        description: Maximum number of objects in the response. Defined by the Provider of the response.
        type: PageSize
      minPageSize?:
          description: Minimum number of objects in the response. Defined by the Provider of the response.
          type: PageSize
          minimum: 1
      self?: Url | nil
      first?: Url | nil
      prev: Url | nil
      next: Url | nil
      last?: Url | nil

  PageNumber:
    description: Page number in case the response is seprated in different pages.
    type: integer
    minimum: 1
    example: 1

  PageSize:
    description: Number of result objects per a single response page. Used for minimum, maximum and/or actual.
    type: integer
    minimum: 1
    maximum: 10000
    example: 10

  PointsValue:
    type: object
    properties:
      coordinates: Position
      value?:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: number
      quality?:
        description: See also value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number

  Position:
    description: |
      A location specified in an array with longitude, lattitude and optional altitude.
    type: Double[]
    minItems: 2
    maxItems: 3
    example: [4.234 , 5.23423]

  Positions:
    description: An array of Positions to specify a MultiPpoint location.
    type: Position[]
    minItems: 0
    examples:
      -multipoint: [[4.2, 52.0], [3.2, 52.3,0]]

  Problem:
    description:  Error response in line with RFC7807. Although both optional the minimum information that should be given are the title and status.
    type: object
    properties:
      type?: Url
      title?: string
      status?:
        type: integer
        description: The HTTP errrocode number.
      detail?: string
      instance?: string | nil
    # Additional fields, RFC7807 extension
      errors?:
        description: Error details.
        type: FilterError[]
      typeinfo?:
        description: Link to information on the type of error.  ??? Why not use 'type'. is link according RFC7807
        type: string | nil

  ProcessName:
    type: string
    description: The name of the mechanism to collect/derive the timeseries value.
      When accessing RWS' DD-API, providing a processName as query parameter is required. The process names are pre-defined (see examples).
      Extending the processname with a suffix, referencing a more detailed mechanism like a specific calculation model, is not allowed.
      Other implementions dot need to implement this query-parameter.
    example: measurement, forecast, astronomical, advise

  Provider:
    type: object
    description: Information regarding the system that is responible for the response.
      Provides support contact information in case there are issues with response format or content.
    properties:
      name?: string
      supportUrl?: string
      apiVersion?: string
      responseType?: string
      responseTimestamp?:
        type: Timestamp
        description: Timestamp when this response was created.

  Quality:
    type: integer

  QuantityName:
    type: string
    description: A name referencing a category of timeseries. The quantity names are predefined.
      For example 'WaterLevel', 'WaterTemperature', 'WaveHeight'.
    example: WaterLevel

  Source:
    description: Describes the type of data in the time series, and the owner of the data.
    type: object
    properties:
      process: ProcessName
      name?:
        type: SourceName
        description: A name describing the source, e.g. a model name.
      description?:
        type: string
        description: Additional description of the data source (might contain a URL to a site with information on the model).
      realizationCount?:
        type: integer
        description: if present, and larger then 1, the results are part of an ensemble run
      institution: Institution

  SourceName:
    type: string
    description: A name describing the source, e.g. a model name
    example: rws_prediction

  StartTime:
    type: datetime
    example: 2016-01-01T12:45:00Z
    description:  Start date/time of the timeseries, or the Start date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.

  Timeseries:
    description: Generic DD API 2.0 timeseries object.DD API 'OPER' response returns a subset of the attributes.
    type: object
    properties:
      node?: Node
      url?: string
      id?: Identifier
      source: Source
      location: Location
      observationType: ObservationType
      startTime: datetime
      endTime: datetime
      analysisTime?: datetime
      realization?: number
      events?:
        type: Event[]
        description: If no startTime and no endTime are provided in the /timeseries-query, only meta-data is provided,
          so the events are not present.

  Timestamp:
    type: string
    description: Date and time in format "yyyy-mmm-ddThh:mm:ss.ffffffZ"  (UTC Zulu with minimal 3 digits of fractional seconds)
    example: "2018-07-05T15:11:36.123Z, 2018-07-05T15:11:36.123456Z, 2018-07-05T15:11:36.000Z"
    minLength: 24

  Url:
    type: string
    description: Correctly formatted url reference.

  Uuid:
    type: string
    pattern: "[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}"
    description: Unique identifier for the datasource. Version 4.
    example: 978fdf5c-95c8-43a5-82ff-d27d9e6d685f

#%RAML 1.0 Library

# Name: dd-base-types.raml
#
# Date: 2018-07-14
#
#  This file defines the basic datatypes used in the DD API and DD-OPER API.

types:
  AdditionalQuality:
    type: integer
    description: Provides detailed information on specific Quality numbers.

  Altitude: number

  Aspect:
    description: A matematical derived variant of a specific measurement, forecast, etc.
    type: object
    properties:
      name: string
      unit: string

  AspectSet:
    description: The AspectSet defines a group of related mathematical values for a single measurement, forecast, etc
    type: object
    properties:
      name: AspectSetName
      aspects:
        type: Aspect[]
        minItems: 0

  AspectSetName:
    description:
    type: string
    default: "standard"
    example: "minimum, maximum, standard, ...."

  AspectPointsValue:
    description: Object used for Event.Aspect.Points. Specifies the values in points array in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      points: PointsValue[]

  AspectValue:
    description: Object used for Event.Aspect[] results. Specifies the value in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      value: number
      quality?: number
      additionalQuality?: number

# BB is not required as object since bbox is only used as query parameter (toch maar laten staan? SH)
  BoundingBox:
    description: The specification of a bounding box using the longitude and latitiude of the most SouthWest point followed by the most NorthEast points (GeoJSON).
    type: Double[]
    minItems: 4
    maxItems: 4
    examples:
      -bbox: [ 4.123456, 52.123456, 10.123456, 55.123456 ]

  Coordinate:
    type: number
    format: double

  Double:
    description: A value of type Double (todo specify #digits/format?).
    type: number
    format: double

  EndTime:
    type: datetime
    example: 2018-01-01T00:00:00Z
    description:  The End date/time of the timeseries, or the End date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.
      The endtime is exlusive, hence the requested period ends just before the given time.
      2018-01-01T00:00:00Z - 2018-01-01T00:00:10Z  specifies a 10 minute period starting at midnight and
      ending at 2018-01-01T00:09:59.99999Z

  Event:
    description: In case of scalar time series the event contains time stamp and value, optionally extended with
      an interval specification (startTime/endTime/resultTime), and a quality indication (quality, additionalQuality).
      In case of a timeseries with Aspects or with values on multiple points, the events contains object for the aspects or points.
    type: object
    properties:
      timeStamp?: datetime
      startTime?: StartTime
      endTime?: EndTime
      resultTime?: datetime
      value?:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: number
      quality?:
        description: See value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number
      aspects?:
        type: AspectValue[] | AspectPointsValue []
        description: When Aspects are used the value/quality/unit are given in and object for each aspect or aspect+point.
      points?:
        type: PointsValue[]
        description: When multiple positions are involved the value/quantity/unit are given in context of each position.

  FilterError:
    type: object
    description: Defines the field of an error in the filtering syntax.
    properties:
      errorType: string
      context: string

  Geometry:
    description: A geometry in GeoJSON format. Digital Delta currently only supports the Point and MultiPoint types.
    type: object
    properties:
      type:
        description: The geometry type. Must have the value "Point" or "MultiPoint".
        type: string
        example: "Point"
      coordinates?:
        description: An array of doubles, representing a Longitude, Latitude and optional Altitude.
        type: Position | Positions
        examples:
          -point:  [4.234 , 5.23423]
          -multipoint:  [[4.2, 52.0], [3.2, 52.3,0]]

  Identifier:
    type: string | Uuid
    description: An uuid or a preferably human readable identifier.

  Institution:
    type: object
    properties:
      name:
        type: string
        description: The name of the institution that produced and/or owns the data
      description?:
        type: string
        description: Additional discription of the institution

# IntervalLength is not required as object since it is only used as query parameter (toch maar laten staan? SH)
  IntervalLength:
    default: 10min

  Location:
    description: Generic DD API 2.0 Location object structure that is used by /dd and /dd-oper. Most attributes are optional as the content returned in the response depends on the request.  Location attributes are placed within the properties group of the GeoJSON  object.
    properties:
      type:
        description: Type of GeoJSON object. In the DD-API the only allowed type is "Feature"
        type: string
        enum: ["Feature"]
      geometry:
        description: The coordinate(s) of the Location are placed within the "geometry" section of the GeoJSON object. DD-API uses Point and Multi-Point locations, but is not restricted to these two.
        type: Geometry | nil
      properties?:
        description: The attributes of Location object are placed within the properties group of the GeoJSON object.
        type: object
        properties:
          node?: Node
          url?: string
          locationId?: string
          locationCode?: string
          referenceLevel?:
            description: GeoJSON element. Specifies the reference plane for the altitude coordinates (third). For example "NAP"
            type: string
          crs?:
            description: GeoJSON element. According to GeoJSON the coordinate reference system element is only included when it is not "WGS84" (default).
            type: string
          locationName?: LocationName
          locationNameSpace?:
            type: LocationNameSpace
          displayNameDetail?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameGlobal?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameSpace?:
            type: LocationNameSpace
            description: Remark, Only used in dd-oper response.
          parentName?:
            type: LocationName
            description: Remark, Only used in dd-oper response.

  LocationName:
    type: string
    example: "Hoek-van-Holland"

  LocationNameSpace:
    type: string
    example: "NL.RWS.WM"

  Node:
    description: Node objects contain the properties of the data node. A node is an operational implementation of the Digital Delta specification.
    type: object
    properties:
      id?:
        type: Identifier
      name:
        type: string
        description: The name of the node.<br/>
      description?:
        type: string
        description: The description of the node.
      baseUrl?:
        type: string
        description: The base URL of the node.

  ObservationType:
    description: Generic DD API 2.0 parameter object. DD-OPER API response returns a subset of the attributes.
    type: object
    properties:
      node?: Node
      url?: Url
      id?: Identifier
      quantityName?:
        description: Composed name of the quantity(.parameterCode) that was measured or computed.
          Remark Only used in dd-oper response.
        type: QuantityName
      parameterCode?:
        description: Parameter code specifying the observationtype. Non-biological observation types follow the Aquo standards.
        type: string
      description?: string
      quantity?: string
      unit?: string
      compartment?:
        description: The compartment in which the measurement/computationt is available. Standardised Aquo compartments.
        type: string
        example:  OW, DL, GW, LW
      aspectSet?:
        description: Optional, currently only provided and used by RWS.
        type: AspectSet

  PageLinks:
    description: The object contains urls and page size information to support back and forward paging
    type: object
    properties:
      totalObjectCount?:
        description: The actual number of objects available. When paging is used the response contains a subset of the total obejcts available up to the max page size.
        type: integer
      maxPageSize?:
        description: Maximum number of objects in the response. Defined by the Provider of the response.
        type: PageSize
      minPageSize?:
          description: Minimum number of objects in the response. Defined by the Provider of the response.
          type: PageSize
          minimum: 1
      self?: Url | nil
      first?: Url | nil
      prev: Url | nil
      next: Url | nil
      last?: Url | nil

  PageNumber:
    description: Page number in case the response is seprated in different pages.
    type: integer
    minimum: 1
    example: 1

  PageSize:
    description: Number of result objects per a single response page. Used for minimum, maximum and/or actual.
    type: integer
    minimum: 1
    maximum: 10000
    example: 10

  PointsValue:
    type: object
    properties:
      coordinates: Position
      value?:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: number
      quality?:
        description: See also value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number

  Position:
    description: |
      A location specified in an array with longitude, lattitude and optional altitude.
    type: Double[]
    minItems: 2
    maxItems: 3
    example: [4.234 , 5.23423]

  Positions:
    description: An array of Positions to specify a MultiPpoint location.
    type: Position[]
    minItems: 0
    examples:
      -multipoint: [[4.2, 52.0], [3.2, 52.3,0]]

  Problem:
    description:  Error response in line with RFC7807. Although both optional the minimum information that should be given are the title and status.
    type: object
    properties:
      type?: Url
      title?: string
      status?:
        type: integer
        description: The HTTP errrocode number.
      detail?: string
      instance?: string | nil
    # Additional fields, RFC7807 extension
      errors?:
        description: Error details.
        type: FilterError[]
      typeinfo?:
        description: Link to information on the type of error.  ??? Why not use 'type'. is link according RFC7807
        type: string | nil

  ProcessName:
    type: string
    description: The name of the mechanism to collect/derive the timeseries value.
      When accessing RWS' DD-API, providing a processName as query parameter is required. The process names are pre-defined (see examples).
      Extending the processname with a suffix, referencing a more detailed mechanism like a specific calculation model, is not allowed.
      Other implementions dot need to implement this query-parameter.
    example: measurement, forecast, astronomical, advise

  Provider:
    type: object
    description: Information regarding the system that is responible for the response.
      Provides support contact information in case there are issues with response format or content.
    properties:
      name?: string
      supportUrl?: string
      apiVersion?: string
      responseType?: string
      responseTimestamp?:
        type: Timestamp
        description: Timestamp when this response was created.

  Quality:
    type: integer

  QuantityName:
    type: string
    description: A name referencing a category of timeseries. The quantity names are predefined.
      For example 'WaterLevel', 'WaterTemperature', 'WaveHeight'.
    example: WaterLevel

  Source:
    description: Describes the type of data in the time series, and the owner of the data.
    type: object
    properties:
      process: ProcessName
      name?:
        type: SourceName
        description: A name describing the source, e.g. a model name.
      description?:
        type: string
        description: Additional description of the data source (might contain a URL to a site with information on the model).
      realizationCount?:
        type: integer
        description: if present, and larger then 1, the results are part of an ensemble run
      institution: Institution

  SourceName:
    type: string
    description: A name describing the source, e.g. a model name
    example: rws_prediction

  StartTime:
    type: datetime
    example: 2016-01-01T12:45:00Z
    description:  Start date/time of the timeseries, or the Start date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.

  Timeseries:
    description: Generic DD API 2.0 timeseries object.DD API 'OPER' response returns a subset of the attributes.
    type: object
    properties:
      node?: Node
      url?: string
      id?: Identifier
      source: Source
      location: Location
      observationType: ObservationType
      startTime: datetime
      endTime: datetime
      analysisTime?: datetime
      realization?: number
      events?:
        type: Event[]
        description: If no startTime and no endTime are provided in the /timeseries-query, only meta-data is provided,
          so the events are not present.

  Timestamp:
    type: string
    description: Date and time in format "yyyy-mmm-ddThh:mm:ss.ffffffZ"  (UTC Zulu with minimal 3 digits of fractional seconds)
    example: "2018-07-05T15:11:36.123Z, 2018-07-05T15:11:36.123456Z, 2018-07-05T15:11:36.000Z"
    minLength: 24

  Url:
    type: string
    description: Correctly formatted url reference.

  Uuid:
    type: string
    pattern: "[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}"
    description: Unique identifier for the datasource. Version 4.
    example: 978fdf5c-95c8-43a5-82ff-d27d9e6d685f

# response types
#
#  The repsonse layouts are of Location object are similar to DD API 1.9 definition except that not all atttributes that are returned,
#  and DD-strict has additional location properties that are not par of the DD API 1.9 specification.

#  LocationListResponse:
#    description: Contains zero or more responses to a Node list request.
#    type: object
#    properties:
#      provider:
#        type: Node
#        description: Reference to the responsible provider for the response.
#     node: Node
#      results:
#        type: Location[]
#        description: List of Location objects
#      count?:
#        description: Number of records satisfying the query parameters.
#        type: integer
#        example: 1123

#  ProblemResponse:
#    description:
#    type: object
#    properties:
#      provider:
#        type: Provider
#      problem:
#        type: Problem


Added event source instances filtered by name

is: [ auth ]
type:
  collection:
    humanName: event source instance
    schemaBaseName: eventSourceInstance
    exampleGetResponse: !include ../examples/eventSourceInstances/response-array-get.json
    examplePostRequest: !include ../examples/eventSourceInstances/request-post.json
    examplePostError: !include ../examples/eventSourceInstances/response-post-error.json
get:
  securedBy: [ jwt: { type: 'owner' }, test ]
  description: |
    You can retrieve the event source instances through:
      * Event source template given through `eventSourceTemplateId`
      * Organization given through `organizationId`
      * All organizations throuhg `allOrganizations`

    At least one of these parementers **MUST** be given. In case, multiple parameters are provided, only one will be
    applied and in this order: `eventSourceTemplateId`, `organizationId` and `allOrganizations`.
  queryParameters:
    eventSourceTemplateId:
      description: |
        Filter the event source instance by event source template.

        The user **MUST** be a member of the organization where the event source instance is configured.
      type: integer
      required: true
      example: |
        `eventSourceTemplateId=1`
    organizationId:
      description: |
        Filter the event source instance by organization.

        The user **MUST** be a member of the organization where the event source instance is configured.
      type: integer
      required: true
      example: |
        `organizationId=1`
    allOrganizations:
      description: Filter the event source instances to retrieve all of them accross all the organizations where the user is member of.
      type: integer
      required: false
      example: |
        `allOrganizations` or `allOrganizations=true`
    name:
      type: string
      required: false
      description: Use this parameter to apply a filter on the name. Can be combined with other parameters.
      example: |
        `name=iFlu%`
  responses:
    200:
      description: List of event types or empty list `[]`.
    422:
      description: If the `eventSourceTemplateId`, `organizationId` or `allOrganizations` is not provided.
    403:
      description: If the user is not a member of the organization that owns the event source instance.
post:
  securedBy: [ jwt: { type: 'owner' }, test ]
  responses:
    403:
      description: If the user is not a member of the organization that owns the event source instance.
    422:
      description: |
        Validation errors.

        You will receive these validations errors:

        * `{ "organizationId": [ "No organization found." ] }` when:
          * No organization found from the ID given
          * You have no access to the organization

        * `{ "eventSourceTemplateId": [ "No event source template found." ] }` when:
          * No event source template found from the ID given
          * You have no access to the event source template
          * You cannot create an event source instance from an event source template in a different organization. In other words
            the organization ID is not the same as event source template organization ID.

/{eventSourceInstanceId}:
  is: [ auth ]
  type:
    member:
      humanName: event source instances
      schemaBaseName: eventSourceInstance
      identifierName: eventSourceInstanceId
      exampleGetResponse: !include ../examples/eventSourceInstances/response-get.json
      examplePatchRequest: !include ../examples/eventSourceInstances/request-patch.json
      examplePatchError: !include ../examples/eventSourceInstances/response-patch-error.json
  get:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the event source instance.
  patch:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the event source instance.

is: [ auth ]
type:
  collection:
    humanName: event source instance
    schemaBaseName: eventSourceInstance
    exampleGetResponse: !include ../examples/eventSourceInstances/response-array-get.json
    examplePostRequest: !include ../examples/eventSourceInstances/request-post.json
    examplePostError: !include ../examples/eventSourceInstances/response-post-error.json
get:
  securedBy: [ jwt: { type: 'owner' }, test ]
  description: |
    You can retrieve the event source instances through:
      * Event source template given through `eventSourceTemplateId`
      * Organization given through `organizationId`
      * All organizations throuhg `allOrganizations`

    At least one of these parementers **MUST** be given. In case, multiple parameters are provided, only one will be
    applied and in this order: `eventSourceTemplateId`, `organizationId` and `allOrganizations`.
  queryParameters:
    eventSourceTemplateId:
      description: |
        Filter the event source instance by event source template.

        The user **MUST** be a member of the organization where the event source instance is configured.
      type: integer
      required: true
      example: |
        `eventSourceTemplateId=1`
    organizationId:
      description: |
        Filter the event source instance by organization.

        The user **MUST** be a member of the organization where the event source instance is configured.
      type: integer
      required: true
      example: |
        `organizationId=1`
    allOrganizations:
      description: Filter the event source instances to retrieve all of them accross all the organizations where the user is member of.
      type: integer
      required: false
      example: |
        `allOrganizations` or `allOrganizations=true`
  responses:
    200:
      description: List of event types or empty list `[]`.
    422:
      description: If the `eventSourceTemplateId`, `organizationId` or `allOrganizations` is not provided.
    403:
      description: If the user is not a member of the organization that owns the event source instance.
post:
  securedBy: [ jwt: { type: 'owner' }, test ]
  responses:
    403:
      description: If the user is not a member of the organization that owns the event source instance.
    422:
      description: |
        Validation errors.

        You will receive these validations errors:

        * `{ "organizationId": [ "No organization found." ] }` when:
          * No organization found from the ID given
          * You have no access to the organization

        * `{ "eventSourceTemplateId": [ "No event source template found." ] }` when:
          * No event source template found from the ID given
          * You have no access to the event source template
          * You cannot create an event source instance from an event source template in a different organization. In other words
            the organization ID is not the same as event source template organization ID.

/{eventSourceInstanceId}:
  is: [ auth ]
  type:
    member:
      humanName: event source instances
      schemaBaseName: eventSourceInstance
      identifierName: eventSourceInstanceId
      exampleGetResponse: !include ../examples/eventSourceInstances/response-get.json
      examplePatchRequest: !include ../examples/eventSourceInstances/request-patch.json
      examplePatchError: !include ../examples/eventSourceInstances/response-patch-error.json
  get:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the event source instance.
  patch:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the event source instance.