mikestahelena / alphavantage-java

Fluent Java wrapper for Alpha Vantage API

I created this wrapper to make accessing the AlphaVantage API fairly simple and fun by providing a fluent interface with Java.

Getting Started

To get started using this library, make sure to get an API Key from Alphavantage's website. Add the library as a dependency to your java/android project

Gradle Installation

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
dependencies {
    ...
    implementation 'com.github.crazzyghost:alphavantage-java:x.y.z'
}

Maven Installation

<repositories>
    ...
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
    ...
</repositories>
<dependencies>
    ...
    <dependency>
        <groupId>com.github.crazzyghost</groupId>
        <artifactId>alphavantage-java</artifactId>
        <version>x.y.z</version>
    </dependency>
    ...
</dependencies>

Quick Usage Guide

These five steps summarize how to access data using this library

1. configure the wrapper
2. Select a category
3. Set the parameters for the selected category
4. Add response callbacks
5. fetch results

1. Configuring the wrapper

Access to the API is through the AlphaVantage Singleton which is accessed using the static api() method of the class. Initialize the singleton with a Config instance once through out your apps lifetime.

Config cfg = Config.builder()
    .key("#&ALPHA10100DEMOKEY")
    .timeOut(10)
    .build();

The config object is then used to initialize the instance. You will use this object to set your api key and configure the http client. Using the wrapper without setting a config or a config key will throw an exception.

AlphaVantage.api().init(cfg);

We're good to go.

2. Selecting a category

Here, we choose which data category/endpoint we want to access

Category	Method
Stock Time Series Data	.timeSeries()
Forex Rate Data	.forex()
Exchange Rate Data	.exchangeRate()
Digital Currency Data	.crypto()
Technical Indicator Data	.indicator()
Sector Performance Data	.sector()

For example, to select the Stock Time Series:

AlphaVantage.api()
    .timeSeries()

3. Setting the parameters for the selected category

To set the api request parameters, call the appopriate parameter methods. For instance for the function parameter function you call daily() for the TIME_SERIES_DAILY function, intraday() for the TIME_SERIES_INTRADAY, and so on.

Let's select the TIME_SERIES_INTRADAY function

AlphaVantage.api()
    .timeSeries()
    .intraday()
...

Start setting parameters by calling an appropriate function method in the selected category

4. Adding response callbacks

To handle responses add the onSuccess() or onFailure() callbacks.

public void handleSuccess(TimeSeriesResponse response) {
    plotGraph(reponse.getStockUnits());
}
public void handleFailure(AlphaVantageException error) {
    /* uh-oh! */
}

AlphaVantage.api()
    .timeSeries()
    .intraday()
    .forSymbol("IBM")
    .interval(Interval.FIVE_MIN)
    .outputSize(OutputSize.FULL)
    .onSuccess(e->handleSuccess(e))
    .onFailure(e->hanldeFailure(e))
    ...

5. fetch results

When you are okay with setting the parameters call the fetch() method. Simple!

AlphaVantage.api()
    .timeSeries()
    .intraday()
    .forSymbol("IBM")
    .interval(Interval.FIVE_MIN)
    .outputSize(OutputSize.FULL)
    .onSuccess(e->handleSuccess(e))
    .onFailure(e->hanldeFailure(e))
    .fetch();

That's it! 🎉 See site for more examples & documentation