swagger: "2.0"
schemes:
  - https
host: dikpeqbnwi3kx.cloudfront.net
info:
  contact:
    x-twitter: HSBC_UK
  title: ATM Locator API
  version: 2.2.1
  x-apisguru-categories:
    - financial
  x-logo:
    url: https://twitter.com/HSBC_UK/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://developer.hsbc.com/assets/swaggers/open-atm-locator-swagger.json
      version: "2.0"
  x-providerName: hsbc.com
  x-serviceName: atm
consumes:
  - application/json
produces:
  - application/prs.openbanking.opendata.v2.2+json
paths:
  /open-banking/v2.2/atms:
    get:
      description: This API will return data about all our ATMs and is prepared to the Open Banking standards as defined by the Open Banking Implementation Entity (OBIE) in data dictionary version 2.2. It is regulated by the UK Competition and Markets Authority (CMA). Data is only available for the United Kingdom.
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/ATMDefinitionMeta"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition400"
        "408":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition408"
        "429":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition429"
        "500":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition500"
        "503":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition503"
      tags:
        - ATMs
  "/x-open-banking/v2.2/atms/country/{country}":
    get:
      description: This extended API will return data about all ATMs in the specified country. It is based-on the Open Banking standards as defined by the Open Banking Implementation Entity (OBIE) in data dictionary version 2.2. The extended functionality may not fully adhere to the non-functional requirements of the regulator. Data is only available for the United Kingdom.
      parameters:
        - description: The ISO country code e.g. &quot;GB&quot;
          in: path
          name: country
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/ATMDefinitionMeta"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition400"
        "408":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition408"
        "429":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition429"
        "500":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition500"
        "503":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition503"
      tags:
        - ATMs
  "/x-open-banking/v2.2/atms/country/{country}/town/{town}":
    get:
      description: This extended API will return data about all ATMs in the specified town. It is based-on the Open Banking standards as defined by the Open Banking Implementation Entity (OBIE) in data dictionary version 2.2. The extended functionality may not fully adhere to the non-functional requirements of the regulator. Data is only available for the United Kingdom.
      parameters:
        - description: The ISO country code e.g. &quot;GB&quot;
          in: path
          name: country
          required: true
          type: string
        - description: Town name, not case sensitive
          in: path
          name: town
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/ATMDefinitionMeta"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition400"
        "408":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition408"
        "429":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition429"
        "500":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition500"
        "503":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition503"
      tags:
        - ATMs
  "/x-open-banking/v2.2/atms/geo-location/lat/{latitude}/long/{longitude}":
    get:
      description: This extended API will data about all ATMs within a specified radius (1 to 10 miles) of the specified latitude and longitude. It is based-on the Open Banking standards as defined by the Open Banking Implementation Entity (OBIE) in data dictionary version 2.2. The extended functionality may not fully adhere to the non-functional requirements of the regulator. Data is only available for the United Kingdom.
      parameters:
        - description: Positive or negative decimal value in degrees. eg &quot;51.50551621597067&quot;
          in: path
          name: latitude
          required: true
          type: string
        - description: Positive or negative decimal value in degrees. eg &quot;-0.0180120225995&quot;
          in: path
          name: longitude
          required: true
          type: string
        - description: Number of miles (1 to 10) as an integer. Default = 1
          in: query
          name: radius
          required: true
          type: number
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/ATMDefinitionMeta"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition400"
        "408":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition408"
        "429":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition429"
        "500":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition500"
        "503":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition503"
      tags:
        - ATMs
  "/x-open-banking/v2.2/atms/postcode/{postcode}":
    get:
      description: This extended API will return data about all ATMs within a 5 mile radius of the specified postcode. It is based-on the Open Banking standards as defined by the Open Banking Implementation Entity (OBIE) in data dictionary version 2.2. The extended functionality may not fully adhere to the non-functional requirements of the regulator. Data is only available for the United Kingdom.
      parameters:
        - description: Letters and numerals only. No spaces or special characters. eg  &quot;SW1A1AA&quot;
          in: path
          name: postcode
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/ATMDefinitionMeta"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition400"
        "408":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition408"
        "429":
          description: Bad request
          schema:
            $ref: "#/definitions/ErrorDefinition429"
        "500":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition500"
        "503":
          description: System error
          schema:
            $ref: "#/definitions/ErrorDefinition503"
      tags:
        - ATMs
definitions:
  ATMDefinition:
    description: Environment of the ATM.
    properties:
      Brand:
        additionalProperties: false
        description: Brand of the Acquirer of transactions captured by the ATM
        items:
          description: Brand of the Acquirer of transactions captured by the ATM
          properties:
            ATM:
              additionalProperties: false
              description: ATM information.
              items:
                description: ATM information.
                properties:
                  ATMServices:
                    description: Describes the type of transaction available for a customer on an ATM.
                    items:
                      description: Describes the type of transaction available for a customer on an ATM.
                      enum:
                        - Balance
                        - BillPayments
                        - CashDeposits
                        - CharityDonation
                        - ChequeDeposits
                        - CashWithdrawal
                        - EnvelopeDeposit
                        - FastCash
                        - MobileBankingRegistration
                        - MobilePaymentRegistration
                        - MobilePhoneTopUp
                        - OrderStatement
                        - Other
                        - PINActivation
                        - PINChange
                        - PINUnblock
                        - MiniStatement
                      type: string
                    title: ATMServices
                    type: array
                  Access24HoursIndicator:
                    description: Indicates that the ATM is available for use by customers 24 hours per day
                    title: Access24HoursIndicator
                    type: boolean
                  Accessibility:
                    description: Indicates Types of Accessibility
                    items:
                      description: Indicates Types of Accessibility
                      enum:
                        - AudioCashMachine
                        - AutomaticDoors
                        - ExternalRamp
                        - InductionLoop
                        - InternalRamp
                        - LevelAccess
                        - LowerLevelCounter
                        - Other
                        - WheelchairAccess
                      type: string
                    title: Accessibility
                    type: array
                  Branch:
                    additionalProperties: false
                    description: Information that locates and identifies a specific branch of a financial institution.
                    properties:
                      Identification:
                        description: Unique and unambiguous identification of a branch of a financial institution.
                        maxLength: 35
                        minLength: 1
                        title: Identification
                        type: string
                    title: Branch
                    type: object
                  Identification:
                    description: ATM terminal device identification for the acquirer and the issuer.
                    maxLength: 35
                    minLength: 1
                    title: Identification
                    type: string
                  Location:
                    additionalProperties: false
                    description: Location of the ATM.
                    properties:
                      LocationCategory:
                        description: Indicates the environment of the ATM.
                        items:
                          description: Indicates the environment of the ATM.
                          enum:
                            - BranchExternal
                            - BranchInternal
                            - BranchLobby
                            - Other
                            - RetailerOutlet
                            - RemoteUnit
                          type: string
                        title: LocationCategory
                        type: array
                      OtherLocationCategory:
                        additionalProperties: false
                        description: Enter a new code , name and description for any other location category
                        items:
                          description: Enter a new code , name and description for any other location category
                          properties:
                            Code:
                              description: The four letter Mnemonic used within an XML file to identify a code
                              maxLength: 4
                              minLength: 0
                              pattern: ^\w{0,4}$
                              title: Code
                              type: string
                            Description:
                              description: Description to describe the purpose of the code
                              maxLength: 350
                              minLength: 1
                              title: Description
                              type: string
                            Name:
                              description: Long name associated with the code
                              maxLength: 70
                              minLength: 1
                              title: Name
                              type: string
                          required:
                            - Name
                            - Description
                          type: object
                        title: OtherLocationCategory
                        type: array
                      PostalAddress:
                        additionalProperties: false
                        description: Information that locates and identifies a specific address, as defined by postal services or in free format text.
                        properties:
                          AddressLine:
                            description: Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text.
                            items:
                              description: maxLength 70 text
                              maxLength: 70
                              minLength: 1
                              type: string
                            maxItems: 7
                            minItems: 0
                            title: AddressLine
                            type: array
                          BuildingNumber:
                            description: Name or Number that identifies the position of a building on a street.
                            maxLength: 350
                            minLength: 1
                            title: BuildingNumber
                            type: string
                          Country:
                            description: Nation with its own government, occupying a particular territory.
                            pattern: "[A-Z]{2}"
                            title: Country
                            type: string
                          CountrySubDivision:
                            description: Identifies a subdivision of a country, for instance state, region, county.
                            items:
                              description: maxLength 35 text
                              maxLength: 35
                              minLength: 1
                              type: string
                            maxItems: 2
                            minItems: 0
                            title: CountrySubDivision
                            type: array
                          GeoLocation:
                            additionalProperties: false
                            description: Geographic location of the ATM specified by geographic coordinates or UTM coordinates.
                            properties:
                              GeographicCoordinates:
                                additionalProperties: false
                                description: Location on the earth specified by two numbers representing vertical and horizontal position.
                                properties:
                                  Latitude:
                                    description: Latitude measured in decimal degrees.
                                    pattern: ^-?\d{1,3}\.\d{1,8}$
                                    title: Latitude
                                    type: string
                                  Longitude:
                                    description: |-
                                      Angular measurement of the distance of a location on the earth east or west of the Greenwich observatory.
                                      The longitude is measured in decimal degrees.
                                    pattern: ^-?\d{1,3}\.\d{1,8}$
                                    title: Longitude
                                    type: string
                                required:
                                  - Latitude
                                  - Longitude
                                title: GeographicCoordinates
                                type: object
                            required:
                              - GeographicCoordinates
                            title: GeoLocation
                            type: object
                          PostCode:
                            description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
                            maxLength: 16
                            minLength: 1
                            title: PostCode
                            type: string
                          StreetName:
                            description: Name of a street or thoroughfare.
                            maxLength: 70
                            minLength: 1
                            title: StreetName
                            type: string
                          TownName:
                            description: Name of a built-up area, with defined boundaries, and a local government.
                            maxLength: 35
                            minLength: 1
                            title: TownName
                            type: string
                        title: PostalAddress
                        type: object
                      Site:
                        additionalProperties: false
                        description: Used by a Financial Institution internally to identify the location of an ATM.
                        properties:
                          Identification:
                            description: ATM site identification for the Financial Institution.
                            maxLength: 35
                            minLength: 1
                            title: Identification
                            type: string
                          Name:
                            description: ATM site name as used by Financial Institution.
                            maxLength: 140
                            minLength: 1
                            title: Name
                            type: string
                        title: Site
                        type: object
                    required:
                      - PostalAddress
                    title: Location
                    type: object
                  MinimumPossibleAmount:
                    description: Minimum amount allowed for a transaction in the service.
                    pattern: ^-?\d{1,10}\.?\d{0,2}$
                    title: MinimumPossibleAmount
                    type: string
                  Note:
                    description: Summary description of the ATM.
                    items:
                      description: maxLength 2000 text
                      maxLength: 2000
                      minLength: 1
                      type: string
                    title: Note
                    type: array
                  OtherATMServices:
                    additionalProperties: false
                    description: Enter a new code , name and description for any other ATM Service
                    items:
                      description: Enter a new code , name and description for any other ATM Service
                      properties:
                        Code:
                          description: The four letter Mnemonic used within an XML file to identify a code
                          maxLength: 4
                          minLength: 0
                          pattern: ^\w{0,4}$
                          title: Code
                          type: string
                        Description:
                          description: Description to describe the purpose of the code
                          maxLength: 350
                          minLength: 1
                          title: Description
                          type: string
                        Name:
                          description: Long name associated with the code
                          maxLength: 70
                          minLength: 1
                          title: Name
                          type: string
                      required:
                        - Name
                        - Description
                      type: object
                    title: OtherATMServices
                    type: array
                  OtherAccessibility:
                    additionalProperties: false
                    description: Enter a new code , name and description for any other ATM accessibility options
                    items:
                      description: Enter a new code , name and description for any other ATM accessibility options
                      properties:
                        Code:
                          description: The four letter Mnemonic used within an XML file to identify a code
                          maxLength: 4
                          minLength: 0
                          pattern: ^\w{0,4}$
                          title: Code
                          type: string
                        Description:
                          description: Description to describe the purpose of the code
                          maxLength: 350
                          minLength: 1
                          title: Description
                          type: string
                        Name:
                          description: Long name associated with the code
                          maxLength: 70
                          minLength: 1
                          title: Name
                          type: string
                      required:
                        - Name
                        - Description
                      type: object
                    title: OtherAccessibility
                    type: array
                  SupportedCurrencies:
                    description: All ISO 4217 defined currency  supported by the ATM.
                    items:
                      description: ISO 4217 defined currency
                      pattern: "[A-Z]{3}"
                      type: string
                    minItems: 1
                    title: SupportedCurrencies
                    type: array
                  SupportedLanguages:
                    description: Identification of the language name according to the ISO 639-1 codes. The type is validated by the list of values coded with two alphabetic characters, defined in the standard.
                    items:
                      description: Identification of the language name according to the ISO 639-1 codes. The type is validated by the list of values coded with two alphabetic characters, defined in the standard.
                      pattern: "[a-z]{2}"
                      type: string
                    title: SupportedLanguages
                    type: array
                required:
                  - Identification
                  - SupportedCurrencies
                  - Location
                type: object
              minItems: 1
              title: ATM
              type: array
            BrandName:
              description: Brand Name that an organisation uses to market its products or services to a consumer
              maxLength: 140
              minLength: 1
              title: BrandName
              type: string
          required:
            - BrandName
            - ATM
          type: object
        minItems: 1
        title: Brand
        type: array
    required:
      - Brand
    type: object
  ATMDefinitionMeta:
    properties:
      data:
        items:
          $ref: "#/definitions/ATMDefinition"
        type: array
      meta:
        $ref: "#/definitions/MetaDefinition"
    required:
      - meta
      - data
  ErrorDefinition400:
    additionalProperties: false
    properties:
      description:
        enum:
          - You have sent a request which could not be understood.
        type: string
      status:
        enum:
          - "400"
        type: string
      title:
        enum:
          - Bad request
        type: string
    required:
      - status
      - title
      - description
    title: 400 Error object
    type: object
  ErrorDefinition408:
    additionalProperties: false
    properties:
      description:
        enum:
          - Your client has failed to submit a request, and a timeout has occurred.
        type: string
      status:
        enum:
          - "408"
        type: string
      title:
        enum:
          - Client timeout
        type: string
    required:
      - status
      - title
      - description
    title: 408 Error object
    type: object
  ErrorDefinition429:
    additionalProperties: false
    properties:
      description:
        enum:
          - You have requested this resource too often. Slow down.
        type: string
      status:
        enum:
          - "429"
        type: string
      title:
        enum:
          - Too many requests
        type: string
    required:
      - status
      - title
      - description
    title: 429 Error object
    type: object
  ErrorDefinition500:
    additionalProperties: false
    properties:
      description:
        enum:
          - An error occurred on the server. No further information is available.
        type: string
      status:
        enum:
          - "500"
        type: string
      title:
        enum:
          - Internal server error
        type: string
    required:
      - status
      - title
      - description
    title: 500 Error object
    type: object
  ErrorDefinition503:
    additionalProperties: false
    properties:
      description:
        enum:
          - The service is temporarily unavailable.
        type: string
      status:
        enum:
          - "503"
        type: string
      title:
        enum:
          - Service temporarily unavailable
        type: string
    required:
      - status
      - title
      - description
    title: 503 Error object
    type: object
  MetaDefinition:
    additionalProperties: false
    properties:
      Agreement:
        enum:
          - Use of the APIs and any related data will be subject to the terms of the Open Licence and subject to terms and conditions
        type: string
      LastUpdated:
        format: date-time
        type: string
      License:
        description: Open Banking License
        enum:
          - https://www.openbanking.org.uk/open-licence
        format: uri
        type: string
      TermsOfUse:
        description: Open Banking Terms of Use
        enum:
          - https://www.openbanking.org.uk/terms
        format: uri
        type: string
      TotalResults:
        type: integer
    required:
      - LastUpdated
      - TotalResults
      - Agreement
      - License
      - TermsOfUse
    title: Meta data
    type: object
