ocbc-vignette

Rachel Lui Win Tan

2019-12-13

Using the OCBCR Package

1. Accessing the APIs

API Key, Secret and Access Token

The Overseas-Chinese Banking Corporation Limited (OCBC) is a Singapore-based bank that has operations spanning 17 countries. OCBC bank provides developers with more than 250 APIs to work with. The APIs fall under the category of Informational and Transactional, with the informational APIs requiring an access token for authorization, and the Transactional APIs requiring OAuth2.0 Authentication.

However the OCBCR package only includes the Informational APIs. All Informational API calls require an access token, which is basically a password through which you can access the API and it helps the OCBC developers to identify who is using their API. Hence please keep your API confidential and do not share it or post it online! In order to use the OCBCR package, please sign up for an API Access Token through this link. You will receive an API Key, an API Secret and an Access Token. You will mostly need the access token to use this package.

In many of the examples in the OCBCR package, the API access token is stored as Sys.getenv("ACC_TOKEN_OCBC"). This means that the API access token is stored in the Renvironment file which keeps it private. You can do this through usethis::edit_r_environ() and assigning your access token like this MY_ACCESS_TOKEN = (your access token). ALL API functions in the OCBCR package require the argument acctoken which is the user’s account token.

Subscriptions

After acquring your access token, you then need to subscribe to the OCBC API(s) that you would like to use. This is quite repetitive, but is very simple to do. For example, if you would like to use the ocbc_accounts function included in this OCBCR package, you would need to subscribe to all the APIs in the ‘Accounts’ category on [this page] (https://api.ocbc.com/store/api_products). You can do this through the API console tab. This way you will be able to these APIs with the same access token. In order to use the full OCBCR package, please subscribe to all the APIs in the “Informational” section.

Installation

This package is not available on CRAN. Please use the following code to install OCBCR on RStudio.

install.packages('devtools')
devtools::install_github('racheltlw/OCBCR', build_vignettes = TRUE)

This will download the OCBCR package from my Github repository into your RStudio. Then you can load the package by calling library(OCBCR).

Using APIs responsibly

The OCBC API is rate limited at 10 API calls per minute, hence Sys.sleep(6) has been included after the GET API calls.

2. OCBCR functions

There are numberous OCBC Informational APIs available and these APIs are grouped into categories based on the information they provide. Usually, an R-package make these APIs accessible individually, with one function corresponding to one API. However, with many of the API calls being very similar, this process can be made more efficient. Each OCBCR function accesses a whole category of APIs, with the individual APIs being accessed by specifying the first argument of the function, the “type”. (e.g By changing the argument account_type in the ocbc_accounts function, the user can access 6 different APIs.)

In total the OCBCR package makes 38 APIs accessible through 7 functions. The Locators and Rates functions also have more interesting functionalities such as plotting interactive maps and graphs.

Locators

This function makes the Locators API category easily accessible in R. The API allows the user to retrieve a list containing a dataframe of information about a specified type of loan, as well as a map (of Singapore or Malaysia) marking out all the locators in that dataframe, plotted according to latitude and longitude.

  • Users may filter the locators by country (Singapore or Malaysia), landmark, latitude, longitude and radius and can consult the documentation for more information
  • Users may leave out optional arguments in order to get a all the locators in the specified category
  • If there is no content retrieved by the API, the function will return an empty dataframe

Here is an example of what you can expect when using ocbc_locators

The dataframe:

library(OCBCR)
locators_example <- ocbc_locator(locator_type = "ATM", acctoken = Sys.getenv("ACC_TOKEN_OCBC"), category = 1, country = "SG")
## API call for ATM successful!
knitr::kable(head(locators_example[[1]])[ , 1:7]) #some formatting for display sake
category address landmark latitude longitude postal code remarks
Atm 446 Pasir Ris Drive 6 #01-112 Pasir Ris Drive 6 - 7-Eleven 1.3703 103.9577 510446
Atm 8 Raffles Avenue #01-K1 Esplanade Mall 1.2895 103.8555 39802
Atm 5 Raffles Place Raffles Place MRT Station 1.2846 103.8515 048618 2 Locations:-Basement 1, B1-13 Raffles Exchange
Atm 30 Raffles Place Level 1 Chevron House 1.2845 103.8519 048622
Atm 1 Tanjong Pagar Road #01-32 Tanjong Pagar Plaza Tanjong Pagar Plaza - 7-Eleven 1.2748 103.8427 082001
Atm 10 Kent Ridge Road Arts and Social Science Faculty National University of Singapore 1.2943 103.7785 119219

And the map:

Rates

This function makes the Rates API category easily accessible in R. The API allows the user to retrieve a dataframe of information about the specified type of rate. Specifically for rate_type = "fixed deposit", the function returns a list containing a dataframe of information, as well as a graph of the fixed deposit interest rates by duration (month) of deposit.

  • Users may filter the locators by local_currency (Singapore or Malaysia), and for rate_ty[e = "forex" they may also filter by foreign_currency and hence find the specific exchange rate.
  • Users may leave out optional arguments in order to get a all the rates in the specified category
  • If there is no content retrieved by the API, the function will return an empty dataframe or list

Here is an example of what you can expect when using ocbc_rates

rates_example <- ocbc_rates("fixed deposit", acctoken = Sys.getenv("ACC_TOKEN_OCBC"))
## API call for fixed deposit successful!
knitr::kable(head(rates_example[[1]]))
duration interest_rate currency disclaimer
1 Month 2.65 MYR The data returned are indicative and are subjected to changes without prior notice. Please use the data at your own discretion and risk.
2 Months 2.65 MYR The data returned are indicative and are subjected to changes without prior notice. Please use the data at your own discretion and risk.
3 Months 2.75 MYR The data returned are indicative and are subjected to changes without prior notice. Please use the data at your own discretion and risk.
4 Months 2.85 MYR The data returned are indicative and are subjected to changes without prior notice. Please use the data at your own discretion and risk.
5 Months 2.85 MYR The data returned are indicative and are subjected to changes without prior notice. Please use the data at your own discretion and risk.
6 Months 2.90 MYR The data returned are indicative and are subjected to changes without prior notice. Please use the data at your own discretion and risk.

Accounts

This function makes the Accounts API category easily accessible in R. The API allows the user to retrieve a dataframe of information about a specified account.

  • Users can check the specific documentation by calling ?ocbc_accounts
  • Users may filter the accounts by country, subcategory, product name and benefit to get a particular account type
  • Users may leave out optional arguments in order to get a full list of all the accounts in the specified category
  • If there is no content retrieved by the API, the function will return an empty dataframe

Here is an example of what you can expect when using ocbc_accounts

Cards

This function makes the Cards API category easily accessible in R. There are 2 main types of information - advisory (card_type = "Credit Advisor or "Debit Advisor") and rewards (card_type = "Credit Promotions" or "Rewards").

  • Note that the Credit Cards category (card_type = "Credit") does not yield information about Credit Card products as the API currently does not return data.
  • Information can be filtered by country, product type, keyword, tag, name, address, category, merchant and price. Users should refer to the documentation for more specific details.
  • Users can also specify limit (default is 10) to increase or decrease the number of items returned. This is applicable to promotions and rewards.

Here is an example of what you can expect when using ocbc_cards

Insurance

This function makes the Insurance API category easily accessible in R. The API allows the user to retrieve a dataframe of information about a specified type of insurance.

  • Users may filter the accounts by subcategory, product name and benefit to get a particular insurance type
  • Users may leave out optional arguments in order to get a full list of all the policies in the specified category
  • If there is no content retrieved by the API, the function will return an empty dataframe

Here is an example of what you can expect when using ocbc_insurance

Investments

This function makes the Investments API category easily accessible in R. The API allows the user to retrieve a dataframe of information about a specified type of investment.

  • Users may filter the investments by product name and benefit to get a particular investment type.
  • Users may leave out optional arguments in order to get a full list of all the investments in the specified category
  • If there is no content retrieved by the API, the function will return an empty dataframe

Here is an example of what you can expect when using ocbc_investments

Loans

This function makes the Loans API category easily accessible in R. The API allows the user to retrieve a dataframe of information about a specified type of loan.

  • Users may filter the loans by subcategory, product name and benefit to get a particular loan type.
  • Users may leave out optional arguments in order to get a full list of all the loans in the specified category
  • If there is no content retrieved by the API, the function will return an empty dataframe

Here is an example of what you can expect when using ocbc_loans