Skip to content

Commit 06b0adc

Browse files
forexrateapiforexrateapi
committed
Initial release v1.3.0 - Official Java SDK for ForexRateAPI
0 parents  commit 06b0adc

File tree

6 files changed

+546
-0
lines changed

6 files changed

+546
-0
lines changed

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
target/
2+
*.class
3+
*.jar
4+
*.war
5+
.idea/
6+
*.iml
7+
.settings/
8+
.classpath
9+
.project

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
MIT License
2+
3+
Copyright (c) 2026 ForexRateAPI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining
6+
a copy of this software and associated documentation files (the
7+
"Software"), to deal in the Software without restriction, including
8+
without limitation the rights to use, copy, modify, merge, publish,
9+
distribute, sublicense, and/or sell copies of the Software, and to
10+
permit persons to whom the Software is furnished to do so, subject to
11+
the following conditions:
12+
13+
The above copyright notice and this permission notice shall be
14+
included in all copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# forexrateapi
2+
3+
forexrateapi is the official Java wrapper for ForexRateAPI.com. This allows you to quickly integrate our foreign exchange rate API and currency conversion API into your application. Check https://forexrateapi.com documentation for more information.
4+
5+
## Installation
6+
7+
### Maven
8+
9+
Add the following dependency to your `pom.xml`:
10+
11+
```xml
12+
<dependency>
13+
<groupId>io.github.forexrateapi</groupId>
14+
<artifactId>forexrateapi</artifactId>
15+
<version>1.3.0</version>
16+
</dependency>
17+
```
18+
19+
### Gradle
20+
21+
Add the following to your `build.gradle`:
22+
23+
```groovy
24+
implementation 'io.github.forexrateapi:forexrateapi:1.3.0'
25+
```
26+
27+
## Usage
28+
29+
```java
30+
import io.github.forexrateapi.client.ForexRateApiClient;
31+
32+
String apiKey = "SET_YOUR_API_KEY_HERE";
33+
ForexRateApiClient client = new ForexRateApiClient(apiKey);
34+
35+
// Or use EU server:
36+
// ForexRateApiClient client = new ForexRateApiClient(apiKey, "eu");
37+
```
38+
---
39+
## Server Regions
40+
41+
ForexRateAPI provides two regional endpoints. Choose the one closest to your servers for optimal performance.
42+
43+
| Region | Base URL |
44+
|--------|----------|
45+
| United States (default) | `https://api.forexrateapi.com/v1` |
46+
| Europe | `https://api-eu.forexrateapi.com/v1` |
47+
48+
```java
49+
import io.github.forexrateapi.client.ForexRateApiClient;
50+
51+
// Default (US)
52+
ForexRateApiClient client = new ForexRateApiClient("SET_YOUR_API_KEY_HERE");
53+
54+
// Europe
55+
ForexRateApiClient client = new ForexRateApiClient("SET_YOUR_API_KEY_HERE", "eu");
56+
```
57+
58+
---
59+
## Documentation
60+
61+
#### fetchSymbols()
62+
```java
63+
client.fetchSymbols();
64+
```
65+
66+
[Link](https://forexrateapi.com/documentation#api_symbol)
67+
68+
---
69+
#### setServer(server)
70+
71+
- `server` <[string]> Pass `"eu"` to use the EU server (`api-eu.forexrateapi.com`), or `"us"` for the US server. Defaults to US if not specified.
72+
73+
```java
74+
client.setServer("eu");
75+
```
76+
77+
---
78+
#### fetchLive(base, currencies, math)
79+
80+
- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
81+
- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
82+
- `math` <[string]> Optional. Pass in a math expression to apply to the rates.
83+
84+
```java
85+
client.fetchLive("USD", List.of("AUD", "CAD", "GBP", "JPY"), "");
86+
```
87+
88+
[Link](https://forexrateapi.com/documentation#api_realtime)
89+
90+
---
91+
#### fetchHistorical(date, base, currencies)
92+
93+
- `date` <[string]> Required. Pass in a string with format `YYYY-MM-DD`
94+
- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
95+
- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
96+
97+
```java
98+
client.fetchHistorical("2024-02-05", "USD", List.of("AUD", "CAD", "GBP", "JPY"));
99+
```
100+
101+
[Link](https://forexrateapi.com/documentation#api_historical)
102+
103+
---
104+
#### hourly(base, currency, startDate, endDate, math, dateType)
105+
106+
- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
107+
- `currency` <[string]> Required. Specify currency you would like to get hourly rates for.
108+
- `startDate` <[string]> Required. Specify the start date using the format `YYYY-MM-DD`.
109+
- `endDate` <[string]> Required. Specify the end date using the format `YYYY-MM-DD`.
110+
- `math` <[string]> Optional. Pass in a math expression to apply to the rates.
111+
- `dateType` <[string]> Optional. Pass in a date type, overrides date parameters if passed in.
112+
113+
```java
114+
client.hourly("USD", "EUR", "2024-02-05", "2024-02-05", "", "");
115+
```
116+
117+
[Link](https://forexrateapi.com/documentation#api_hourly)
118+
119+
---
120+
#### fetchOHLC(base, currency, date, dateType)
121+
122+
- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
123+
- `currency` <[string]> Required. Specify currency you would like to get OHLC for.
124+
- `date` <[string]> Required. Specify date to get OHLC for specific date using format `YYYY-MM-DD`.
125+
- `dateType` <[string]> Optional. Pass in a date type, overrides date parameter if passed in.
126+
127+
```java
128+
client.fetchOHLC("USD", "EUR", "2024-02-05", "");
129+
```
130+
131+
[Link](https://forexrateapi.com/documentation#api_ohlc)
132+
133+
---
134+
#### convert(fromCurrency, toCurrency, amount, date)
135+
136+
- `fromCurrency` <[string]> Optional. Pass in a base currency, defaults to USD.
137+
- `toCurrency` <[string]> Required. Specify currency you would like to convert to.
138+
- `amount` <[number]> Required. The amount to convert.
139+
- `date` <[string]> Optional. Specify date to use historical midpoint value for conversion with format `YYYY-MM-DD`. Otherwise, it will use live exchange rate date if value not passed in.
140+
141+
```java
142+
client.convert("USD", "EUR", 100, "2024-02-05");
143+
```
144+
145+
[Link](https://forexrateapi.com/documentation#api_convert)
146+
147+
---
148+
#### timeframe(startDate, endDate, base, currencies)
149+
150+
- `startDate` <[string]> Required. Specify the start date of your timeframe using the format `YYYY-MM-DD`.
151+
- `endDate` <[string]> Required. Specify the end date of your timeframe using the format `YYYY-MM-DD`.
152+
- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
153+
- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
154+
155+
```java
156+
client.timeframe("2024-02-05", "2024-02-06", "USD", List.of("AUD", "CAD", "GBP", "JPY"));
157+
```
158+
159+
[Link](https://forexrateapi.com/documentation#api_timeframe)
160+
161+
---
162+
#### change(startDate, endDate, base, currencies, dateType)
163+
164+
- `startDate` <[string]> Required. Specify the start date of your timeframe using the format `YYYY-MM-DD`.
165+
- `endDate` <[string]> Required. Specify the end date of your timeframe using the format `YYYY-MM-DD`.
166+
- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
167+
- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
168+
- `dateType` <[string]> Optional. Pass in a date type, overrides date parameters if passed in.
169+
170+
```java
171+
client.change("2024-02-05", "2024-02-06", "USD", List.of("AUD", "CAD", "GBP", "JPY"), "");
172+
```
173+
174+
[Link](https://forexrateapi.com/documentation#api_change)
175+
176+
---
177+
#### usage()
178+
```java
179+
client.usage();
180+
```
181+
182+
[Link](https://forexrateapi.com/documentation#api_usage)
183+
184+
---
185+
**[Official documentation](https://forexrateapi.com/documentation)**
186+
187+
---
188+
## FAQ
189+
190+
- How do I get an API Key?
191+
192+
Free API Keys are available [here](https://forexrateapi.com).
193+
194+
- I want more information
195+
196+
Checkout our FAQs [here](https://forexrateapi.com/faq).
197+
198+
199+
## Support
200+
201+
For support, get in touch using [this form](https://forexrateapi.com/contact).
202+
203+
204+
[List]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/List.html 'List'
205+
[number]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Number.html 'Number'
206+
[string]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html 'String'

‎example/Example.java‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import io.github.forexrateapi.client.ForexRateApiClient;
2+
import org.json.JSONObject;
3+
4+
import java.util.List;
5+
6+
public class Example {
7+
public static void main(String[] args) throws Exception {
8+
String apiKey = "REPLACE_ME";
9+
ForexRateApiClient client = new ForexRateApiClient(apiKey);
10+
11+
// Or use EU server:
12+
// ForexRateApiClient client = new ForexRateApiClient(apiKey, "eu");
13+
14+
JSONObject result;
15+
16+
result = client.fetchSymbols();
17+
System.out.println(result);
18+
19+
result = client.fetchLive("USD", List.of("AUD", "CAD", "GBP", "JPY"), "");
20+
System.out.println(result);
21+
22+
result = client.fetchHistorical("2024-02-05", "USD", List.of("AUD", "CAD", "GBP", "JPY"));
23+
System.out.println(result);
24+
25+
result = client.hourly("USD", "EUR", "2024-02-05", "2024-02-05", "", "");
26+
System.out.println(result);
27+
28+
result = client.fetchOHLC("USD", "EUR", "2024-02-05", "");
29+
System.out.println(result);
30+
31+
result = client.convert("USD", "EUR", 100, "2024-02-05");
32+
System.out.println(result);
33+
34+
result = client.timeframe("2024-02-05", "2024-02-06", "USD", List.of("AUD", "CAD", "GBP", "JPY"));
35+
System.out.println(result);
36+
37+
result = client.change("2024-02-05", "2024-02-06", "USD", List.of("AUD", "CAD", "GBP", "JPY"), "");
38+
System.out.println(result);
39+
40+
result = client.usage();
41+
System.out.println(result);
42+
}
43+
}

‎pom.xml‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>io.github.forexrateapi</groupId>
8+
<artifactId>forexrateapi</artifactId>
9+
<version>1.3.0</version>
10+
<packaging>jar</packaging>
11+
12+
<name>ForexRateAPI</name>
13+
<description>Official Java wrapper for ForexRateAPI.com - Foreign exchange rate API and currency conversion API</description>
14+
<url>https://forexrateapi.com</url>
15+
16+
<developers>
17+
<developer>
18+
<name>ForexRateAPI</name>
19+
<email>contact@forexrateapi.com</email>
20+
<organization>ForexRateAPI</organization>
21+
<organizationUrl>https://forexrateapi.com</organizationUrl>
22+
</developer>
23+
</developers>
24+
25+
<scm>
26+
<connection>scm:git:git://github.com/forexrateapi/forexrateapi-java.git</connection>
27+
<developerConnection>scm:git:ssh://github.com:forexrateapi/forexrateapi-java.git</developerConnection>
28+
<url>https://github.com/forexrateapi/forexrateapi-java</url>
29+
</scm>
30+
31+
<licenses>
32+
<license>
33+
<name>MIT License</name>
34+
<url>https://opensource.org/licenses/MIT</url>
35+
</license>
36+
</licenses>
37+
38+
<properties>
39+
<maven.compiler.source>11</maven.compiler.source>
40+
<maven.compiler.target>11</maven.compiler.target>
41+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
42+
</properties>
43+
44+
<dependencies>
45+
<dependency>
46+
<groupId>org.json</groupId>
47+
<artifactId>json</artifactId>
48+
<version>20231013</version>
49+
</dependency>
50+
</dependencies>
51+
52+
<build>
53+
<plugins>
54+
<plugin>
55+
<groupId>org.apache.maven.plugins</groupId>
56+
<artifactId>maven-compiler-plugin</artifactId>
57+
<version>3.11.0</version>
58+
<configuration>
59+
<source>11</source>
60+
<target>11</target>
61+
</configuration>
62+
</plugin>
63+
<plugin>
64+
<groupId>org.apache.maven.plugins</groupId>
65+
<artifactId>maven-source-plugin</artifactId>
66+
<version>3.3.0</version>
67+
<executions>
68+
<execution>
69+
<id>attach-sources</id>
70+
<goals><goal>jar-no-fork</goal></goals>
71+
</execution>
72+
</executions>
73+
</plugin>
74+
<plugin>
75+
<groupId>org.apache.maven.plugins</groupId>
76+
<artifactId>maven-javadoc-plugin</artifactId>
77+
<version>3.6.3</version>
78+
<executions>
79+
<execution>
80+
<id>attach-javadocs</id>
81+
<goals><goal>jar</goal></goals>
82+
</execution>
83+
</executions>
84+
</plugin>
85+
<plugin>
86+
<groupId>org.apache.maven.plugins</groupId>
87+
<artifactId>maven-gpg-plugin</artifactId>
88+
<version>3.1.0</version>
89+
<executions>
90+
<execution>
91+
<id>sign-artifacts</id>
92+
<phase>verify</phase>
93+
<goals><goal>sign</goal></goals>
94+
</execution>
95+
</executions>
96+
</plugin>
97+
<plugin>
98+
<groupId>org.sonatype.central</groupId>
99+
<artifactId>central-publishing-maven-plugin</artifactId>
100+
<version>0.6.0</version>
101+
<extensions>true</extensions>
102+
<configuration>
103+
<publishingServerId>forexrateapi</publishingServerId>
104+
</configuration>
105+
</plugin>
106+
</plugins>
107+
</build>
108+
</project>

0 commit comments

Comments
 (0)