openapi: 3.0.1
info:
  title: GeoScore
  description: A service that provides the values (geographic score) of the Credit Information Bureau (BIK) credit score for the geographic area (address or UTM coordinates) specified by the service recipient. / Usługa udostępniająca wartości (score geograficzny) oceny punktowej Biura Informacji Kredytowego (BIK) dla określonego przez usługobiorcę obszaru geograficznego (adres lub współrzędne utm).
  version: '1.0'
servers:
  - url: http://gateway.oapi.bik.pl/bik-api-5
  - url: https://gateway.oapi.bik.pl/bik-api-5
paths:
  /geoscore-utm:
    post:
      tags:
        - współrzędne
      summary: Gescore by UTM coordinates.
      description: Download the score for the indicated geographic coordinates in the UTM system (in meters). / Pobranie score dla wskazanych współrzędnych geograficznych w układzie UTM (w metrach).
      operationId: geoscoreByUtmLoc
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UtmLocRequestWrapper'
            example:
              localization:
                utm_x: 400000
                utm_y: 5729510
              date: '202301'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoscoringUtmlocResponse'
              example:
                inputDataLocalization:
                  utm_x: 400000
                  utm_y: 5729510
                radius: '50'
                score: '89'
        '400':
          description: The request will be rejected during business rule validation (validation errors). / Żądanie zostanie odrzucone podczas walidacji reguł biznesowych (błędy walidacji).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                errors:
                  - propertyName: buildingNumber
                    rejectedValue: 111111111111111111111111111111111111111112
                    details: The size must be in the range from 1 to 12.
                  - propertyName: code
                    rejectedValue: '9144'
                    details: Code must be in 'XXXXX' format.
                  - propertyName: city
                    rejectedValue: Ł
                    details: The size must be in the range from 2 to 255.
                  - propertyName: street
                    rejectedValue: ''
                    details: Value cannot be null.
                message: Incorrect input data.
        '402':
          description: The call limit has been exceeded. / Przekroczono limit wywołań.
        '404':
          description: 'The indicated point was not found in the database of addresses or geographic coordinates, or no data was found in the database for the indicated area (no scoring data). / Nie odnaleziono wskazanego punktu w bazie adresów lub współrzędnych geograficznych lub nie odnaleziono danych w bazie dla wskazanego obszaru (brak danych scoringowych).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
              example:
                message: The indicated point or geographic coordinates were not found.
        '500':
          description: A request processing error occurred. / Wystąpiły błędy przetwarzania żądania.
        '503':
          description: Service is unavailable. / Usługa jest niedostępna.
  /geoscore-adres:
    post:
      tags:
        - adres
      summary: Gescore by address.
      description: Download score for the indicated address. / Pobranie score dla wskazanago adresu.
      operationId: geoscoreByAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequestWrapper'
            example:
              address:
                code: '90425'
                city: Łódź
                street: Piotrkowska
                building_number: '101'
              date: '202301'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoscoringAddressResponse'
              example:
                radius: '50'
                score: '89'
                inputDataAddress:
                  code: '90425'
                  city: Łódź
                  street: Piotrkowska
                  building_number: '101'
                nearestPoint:
                  code: '90425'
                  city: Łódź
                  street: Piotrkowska
                  building_number: '100'
        '400':
          description: The request will be rejected during business rule validation (validation errors). / Żądanie zostanie odrzucone podczas walidacji reguł biznesowych (błędy walidacji).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                errors:
                  - propertyName: buildingNumber
                    rejectedValue: 111111111111111111111111111111111111111112
                    details: The size must be in the range from 1 to 12.
                  - propertyName: code
                    rejectedValue: '9144'
                    details: Code must be in 'XXXXX' format.
                  - propertyName: city
                    rejectedValue: Ł
                    details: The size must be in the range from 2 to 255.
                  - propertyName: street
                    rejectedValue: ''
                    details: Value cannot be null.
                message: Incorrect input data.
        '402':
          description: The call limit has been exceeded. / Przekroczono limit wywołań.
        '404':
          description: 'The indicated point was not found in the database of addresses or geographic coordinates, or no data was found in the database for the indicated area (no scoring data). / Nie odnaleziono wskazanego punktu w bazie adresów lub współrzędnych geograficznych lub nie odnaleziono danych w bazie dla wskazanego obszaru (brak danych scoringowych).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
              example:
                message: The indicated point or geographic coordinates were not found.
        '500':
          description: A request processing error occurred. / Wystąpiły błędy przetwarzania żądania.
        '503':
          description: Service is unavailable. / Usługa jest niedostępna.
components:
  schemas:
    CoordinatesUtm:
      type: object
      properties:
        utm_x:
          type: number
          description: X coordinate in UTM system. / Współrzędna X w układzie UTM.
          format: double
        utm_y:
          type: number
          description: Y coordinate in UTM system. / Współrzędna Y w układzie UTM.
          format: double
      description: Geographic coordinates in the UTM system. / Współrzędne geograficzne w układzie UTM.
    Address:
      required:
        - building_number
        - city
        - code
        - street
      type: object
      properties:
        code:
          pattern: '[0-9]{5}'
          type: string
          description: Postal code in XXXXX format. / Kod pocztowy w formacie XXXXX.
        city:
          maxLength: 255
          minLength: 2
          type: string
          description: City / Miasto
        street:
          type: string
          description: Street / Ulica
        building_number:
          maxLength: 12
          minLength: 1
          type: string
          description: Building number / Numer budynku
      description: Address information / Dane adresowe
    ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            required:
              - propertyName
              - rejectedValue
              - details
            type: object
            properties:
              propertyName:
                type: string
              rejectedValue:
                type: string
              details:
                type: string
        message:
          type: string
    ErrorNotFound:
      type: object
      properties:
        message:
          type: string
          description: The indicated point or geographic coordinates were not found. / Nie odnaleziono wskazanego punktu lub współrzędnych geograficznych.
      example:
        message: The indicated point or geographic coordinates were not found.
    AddressRequestWrapper:
      required:
        - address
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        date:
          type: string
    UtmLocRequestWrapper:
      required:
        - localization
      type: object
      properties:
        localization:
          $ref: '#/components/schemas/CoordinatesUtm'
        date:
          type: string
    GeoscoringUtmlocResponse:
      type: object
      properties:
        inputDataLocalization:
          $ref: '#/components/schemas/CoordinatesUtm'
        radius:
          type: string
          description: Approximate radius of the circle (in meters) from which Scoring was used to calculate the Score / Przybliżony promień koła (w metrach) z jakiego wykorzystano Scoringi do wyliczenia Oceny Punktowej
        score:
          type: string
          description: Integer (average score from BIKSco CreditRisk3 score model) / Liczba całkowita (średnia ocena z modelu score BIKSco CreditRisk3)
        date:
          type: string
    GeoscoringAddressResponse:
      type: object
      properties:
        inputDataAddress:
          $ref: '#/components/schemas/Address'
        nearestPoint:
          $ref: '#/components/schemas/Address'
        inputDataLocalization:
          $ref: '#/components/schemas/CoordinatesUtm'
        radius:
          type: string
          description: Approximate radius of the circle (in meters) from which Scoring was used to calculate the Score / Przybliżony promień koła (w metrach) z jakiego wykorzystano Scoringi do wyliczenia Oceny Punktowej
        score:
          type: string
          description: Integer(average score from BIKSco CreditRisk3 score model) / Liczba całkowita (średnia ocena z modelu score BIKSco CreditRisk3)
        date:
          type: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: BIK-OAPI-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: bik-oapi-Key
      in: query
security:
  - apiKeyHeader: [ ]
  - apiKeyQuery: [ ]