ATM Locator API Specification

1. Version Control
2. Overview
3. Specification
   1. Data Dictionary
   2. Swagger
4. Message Implementation Guide
   1. Purpose
   2. Format Notation
   3. Implementation Notes
5. ATM Top Level Design
6. Usage Examples
   1. Common Request for Usage Examples
   2. Sample implementation HSBC Bank ATM at DE78DD

# Version Control

# Overview

This specification includes all relevant artefacts for the Open Data ATM API Specification.

This endpoint can contain multiple brands owned by a particular banking group. Each brand can provide multiple ATMs.

An ATM consists of:-

• A unique Identification

• ATMServices - a pre-defined set of standard code names defining services available from an ATM e.g. PinUnblock.

• OtherATMServices - allows a bank to add it's own non-standard/proprietary codes, code names and descriptions.

• Accessibility - a pre-defined set of standard code names defining accessibility features that the ATM offers e.g. InductionLoop

• OtherAccessibility - allows a bank to add it's own non-standard/proprietary codes, code names and descriptions.

• Supported Languages - the 2-digit ISO 639-1 language code.

• Location - This is where the ATM is located and is a mix of a postal address and the geographic coordinates (decimal Latitude and Longitude). Postal address information can either be:-

  i) Up to 7 lines of unstructured address information (AddressLine)

  ii) Structured address information e.g. BuildingNumber, StreetName, Town, PostCode etc or a mixture of both.

  Location is very important so the API provider should ensure that either geographical coordinates (preferred) or a combination of building number and postcode are supplied so that the ATM can be accurately located on a map.

• Base currency - currently restricted to 'GBP' only, but may be extended in future to cope with other currencies dispensed by ATMs at airports, for example, if the API providers are able to supply this information.

• Minimum possible amount - This will inform a consumer as the minimum possible amount that they can withdraw from an ATM. Note: This is not the same as the minimum denomination. For example, an ATM may dispense £5 notes but require the consumer to withdraw a minimum possible amount of £10.

# Specification

The following UML Class Diagram provides the hierarchical structure of the message in a graphical form, which is easier to digest.

# Data Dictionary

Provides detailed description for each fields in the message specification along with the associated code lists, constraints and other technical details such as cardinality, any pattern constraints, min, max length etc.

atml.2.3.0.tabbeddd.xlsx

# Swagger

The API specification written using the Swagger API specification format.

atml.2.3.0.swagger.json

# Message Implementation Guide

# Purpose

The message implementation guide (MIG) is designed to assist the implementers of the messaging specification by providing worked examples as to how the message fields should be completed in different scenarios.

The intention is that this will better ensure consistency. This guide should be read alongside the data dictionary which provides fuller information about the rules, constraints and guidelines that should be adhered to when populating the fields.

# Format Notation

The format that we use in this document for field value assignment is:-

• [] enclose a set of field values.

Where there are multiple records for a particular field, we depict this as [<record 1 value1>, <record 1 value2>…<recordn valuen>], whilst where we are showing that there is 1 field value in 1 record, and another field value in a 2nd record, I depict this as [<record1 value1>],[<record 2 value 1>],[<record 3 value 3>]

• , separates individual field values within a field value set.

• " surrounds a text or date field value.

# Implementation Notes

Before implementing the message standard, it is useful browsing current ATM Locator websites e.g. Link ATM Locator, Visa ATM Locator and Mastercard , along with the ATM Locator webpages provided by your own organisation, in order to get a feel as to why you need to supply this information.

# ATM Top Level Design

# Usage Examples

The Usage Examples are representative of different functional scenarios and are given in JSON format.

For simplicity, some of the mandatory JSON elements may be skipped to keep the size of the response manageable for this document, to highlight only on the relevant items. For example, when we are giving example of CreditInterest, then we might not show Overdraft and other json elements, to keep the JSON response size manageable.

# Common Request for Usage Examples

Request

GET /atms HTTP/1.1
Accept: application/json

# Sample implementation HSBC Bank ATM at DE78DD

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Type: application/prs.openbanking.opendata.v2.2

{
  "data": [
    {
      "Brand": [
        {
          "BrandName": "UK",
          "ATM": [
            {
              "Identification": "AB461881",
              "SupportedLanguages": [
                "en",
                "fr",
                "es",
                "de"
             ],
              "ATMServices": [
                "CashWithdrawal",
                "PINChange",
                "MobilePhoneTopUp",
                "Balance",
                "MiniStatement",
                "CharityDonation"
             ],
              "SupportedCurrencies": [
                "GBP"
             ],
              "MinimumPossibleAmount": "5",
              "Branch": {
                "Identification": "402529"
              },
              "Location": {
                "Site": {
                  "Name": "ILKESTON I1"
                },
                "PostalAddress": {
                  "StreetName": "63 Bath Street",
                  "TownName": "ILKESTON",
                  "Country": "GB",
                  "PostCode": "DE7 8DD",
                  "GeoLocation": {
                    "GeographicCoordinates": {
                      "Latitude": "52.9740105",
                      "Longitude": "-1.3090999"
                    }
                  }
                }
              }
            }
         ]
        }
     ]
    }
 ]
}