Documentation

Our Currency API provides the conversion rates for the most common currencies and based on the official banks data.
It also includes historical data for the last 10 years.

256-bit SSL encryption is used to provide the secure communication with our API.

This documentation describes features of API, endpoints and provides integration guides.

Authentication

In order to get an access to the API you need to get the api key. Each user after the registration and email validation would be able to get it in the account dashboard.

To use your api key you need to append api_key parameter to every request. Please see the example below.

GET: https://api.getgeoapi.com/api/v2/currency/list?api_key={YOUR_API_KEY}

Formats

We currently support JSON and XML formats. To specify the formant you need to attach the format parameter to the request as shown in the example below

GET: https://api.getgeoapi.com/api/v2/currency/list
?api_key={YOUR_API_KEY}
&format={FORMAT}

format parameter can have the following options:

  • json
  • xml


Endpoints

Please remember to add your api_key to every request.

The endpoint below returns the list of all supported currencies. You can find more information about it in the Currencies List section.

GET: https://api.getgeoapi.com/api/v2/currency/list

The endpoint below converts one currency to another. You can find more information about it in the Currency Conversion section.

GET: https://api.getgeoapi.com/api/v2/currency/convert

The endpoint provides exchange rates on the specific day. You can find more information about it in the Historical Currency section.

GET: https://api.getgeoapi.com/api/v2/currency/historical/{YYYY-MM-DD}

Currencies List

Currencies List Lookup returns the list of all supported currencies.

Endpoint:

GET: https://api.getgeoapi.com/api/v2/currency/list

Example request:

GET: https://api.getgeoapi.com/api/v2/currency/list
?api_key={YOUR_API_KEY}
&format=json

Request parameters:

Parameter Description
api_key (required) Api Key that every registered user has and can be found in the Dashboard
format (optional) Specifies the output format. It can be json or xml

Response example:

{
    "status":"success",
    "currencies":{
        "AUD":"Australian Dollar",
        "BGN":"Bulgarian Lev",
         ...
    }
}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <status>success</status>
    <currencies>
        <USD>US Dollar</USD>
        <IDR>Indonesian Rupiah</IDR>
        [ ... ]
    </currencies>
</root>

Response object:

Property Description
status Returns the status of the request. Can be 'success' or 'fail'.
currencies Returns code and name of the supported currencies.

Currency Conversion

Currency Conversion Lookup converts one currency to another.

Endpoint:

GET: https://api.getgeoapi.com/api/v2/currency/convert

Example request:

GET: https://api.getgeoapi.com/api/v2/currency/convert
?api_key={YOUR_API_KEY}
&from=EUR
&to=GBP
&amount=10
&format=json

Request parameters:

Parameter Description
api_key (required) Api Key that every registered user has and can be found in the Dashboard
from (optional) Specifies the base currency.The default base currency is EUR.
to (required for Free Plan and optional for other plans) Specifies the currency to convert to. If the value is not provided then the list of all supported currencies will be returned.
amount (optional) Specifies the amount that needs to be converted. The default value is 1.
format (optional) Specifies the output format. It can be json or xml

Response example:

{
    "status":"success",
    "updated_date":"2018-12-27",
    "base_currency_code":"EUR",
    "amount":10,"
    "base_currency_name":"Euro",
    rates":{
        "GBP":{
            "currency_name":"Pound Sterling",
            "rate":"0.9007",
            "rate_for_amount":"9.0070"
        }
    }
}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <status>success</status>
    <updated_date>2018-12-27</updated_date>
    <base_currency_code>EUR</base_currency_code>
    <base_currency_name>Euro</base_currency_name>
    <amount>10</amount>
    <rates>
        <GBP>
            <currency_name>Pound Sterling</currency_name>
            <rate>0.9007</rate>
            <rate_for_amount>9.0070</rate_for_amount>
        </GBP>
    </rates>
</root>

Response object:

Property Description
status Returns the status of the request. Can be 'success' or 'fail'.
updated_date Returns the date when the currency rate was updated.
base_currency_code Returns the base currency code.
base_currency_name Returns the base currency name.
amount Returns the amount that needs to be converted.
rates Returns all exchange rate values. Each rate object includes:
  • currency_name: Name of the required currency
  • rate: The conversion rate value for amount = 1
  • rate_for_amount: The conversion rate value for requested amount

Historical Currency

Currency Conversion Lookup converts one currency to another.

Endpoint:

GET: https://api.getgeoapi.com/api/v2/currency/historical/{YYYY-MM-DD}

Example request:

GET: https://api.getgeoapi.com/api/v2/currency/historical/2018-10-12
?api_key={YOUR_API_KEY}
&from=EUR
&to=GBP
&amount=10
&format=json

Request parameters:

Parameter Description
api_key (required) Api Key that every registered user has and can be found in the Dashboard
date (required) Specifies the date for which to request rates. The format of the date is YYYY-MM-DD.
from (optional) Specifies the base currency.The default case currency is EUR.
to (required for Free Plan and optional for others) Specifies the currency to convert to. If the value is not provided then the list of all supported currencies will be returned.
amount (optional) Specifies the amount that needs to be converted. The default value is 1.
format (optional) Specifies the output format. It can be json or xml

Response example:

{
    "status":"success",
    "updated_date":"2018-10-12",
    "base_currency_code":"EUR",
    "amount":10,"
    "base_currency_name":"Euro",
    rates":{
        "GBP":{
            "currency_name":"Pound Sterling",
            "rate":"0.8764",
            "rate_for_amount":"8.7640"
        }
    }
}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <status>success</status>
    <updated_date>2018-10-12</updated_date>
    <base_currency_code>EUR</base_currency_code>
    <base_currency_name>Euro</base_currency_name>
    <amount>10</amount>
    <rates>
        <GBP>
            <currency_name>Pound Sterling</currency_name>
            <rate>0.8764</rate>
            <rate_for_amount>8.7640</rate_for_amount>
        </GBP>
    </rates>
</root>

Response object:

Property Description
status Returns the status of the request. Can be 'success' or 'fail'.
updated_date Returns the date when the currency rate was updated.
base_currency_code Returns the base currency code.
base_currency_name Returns the base currency name.
amount Returns the amount that needs to be converted.
rates Returns all exchange rate values. Each rate object includes:
  • currency_name: Name of the required currency
  • rate: The conversion rate value for amount = 1
  • rate_for_amount: The conversion rate value for requested amount

Errors

In case the request fails or the resource is not available the error will be returned in JSON or XML format.

Error response example:

{
    "status":"failed",
    "error":{
        "message":"Invalid key.",
        "code":"403"
    }
}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <status>failed</status>
    <error>
        <message>Invalid key.</message>
        <code>403</code>
    </error>
</root>

Error codes:

Code Description
400 Bad request.
403
  • Authentication credentials were not provided.
  • Invalid key.
  • You reached the limit of your requests.
  • User is not active. Please use the link in the email to activate the user.
404 Resource is not found or requested format is incorrect
405 Method is not allowed.
500 Server error. We hope you will never see this error.

Code Examples

PHP example:

<?php

$key = "{YOUR_API_KEY}";

$url = "https://api.getgeoapi.com/api/v2/currency/list?api_key=".$key."&format=json";

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($curl);
curl_close($curl);

$json = json_decode($response, true);

print_r($json);

?>

Python example:

import requests

key = "{YOUR_API_KEY}"

parameters = {"api_key": key "format": "json"}

url = "https://api.getgeoapi.com/api/v2/currency/list

response = requests.get(url, parameters)

print(response.json())

Javascript example:

var key = "{YOUR_API_KEY}";

var url =  "https://api.getgeoapi.com/api/v2/currency/list?api_key=" + key + "&format=json"

$.getJSON(url, function (data) {
    console.log(data);
});
Check our Geo Location API Try Geo Location API