Documentation

Authentication

After signing up and validating your email, you will be able to find your API Key in your dashboard.

To make a request, you will need to append an api_key query parameter to every request.

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

Formats

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

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

The 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/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/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/v2/currency/historical/{YYYY-MM-DD}

Currencies List

Currencies List Lookup returns the list of all supported currencies.

Endpoint:

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

Example request:

GET: https://api.getgeoapi.com/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) 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/v2/currency/convert

Example request:

GET: https://api.getgeoapi.com/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) The base currency.The default base currency is EUR.
to (required for Free Plan and optional for other plans) The currency to convert to. If the value is not provided then a list of all supported currencies will be returned.
amount (optional) The amount that needs to be converted. The default value is 1.
format (optional) 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 The status of the request. Can be 'success' or 'fail'.
updated_date The date when the currency rate was updated.
base_currency_code The base currency code.
base_currency_name The base currency name.
amount The amount that needs to be converted.
rates The exchange rates values. Each exchange rates object contains:
  • 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/v2/currency/historical/{YYYY-MM-DD}

Example request:

GET: https://api.getgeoapi.com/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 can be found in the dashboard
date (required) The date for which to request rates. The format of the date is YYYY-MM-DD.
from (optional) The base currency.The default case currency is EUR.
to (required for Free Plan and optional for others) The currency to convert to. If the value is not provided then the list of all supported currencies will be returned.
amount (optional) The amount that needs to be converted. The default value is 1.
format (optional) 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 The status of the request. Can be 'success' or 'fail'.
updated_date The date when the currency rate was updated.
base_currency_code The base currency code.
base_currency_name The base currency name.
amount The amount that needs to be converted.
rates The exchange rates values. Each exchange rates object contains:
  • 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 an 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/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/v2/currency/list

response = requests.get(url, parameters)

print(response.json())

JavaScript ES6 example:

const key = "{YOUR_API_KEY}";

const url =  `https://api.getgeoapi.com/v2/currency/list?api_key=${key}&format=json`

fetch(url)
  .then(response => response.json())
  .then(data => console.log(data));

JavaScript/jQuery example:

var key = "{YOUR_API_KEY}";

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

$.getJSON(url, function (data) {
    console.log(data);
});

Curl example:

curl --request GET \
--url 'https://api.getgeoapi.com/v2/currency/list?api_key={YOUR_API_KEY}

Unofficial Libraries

C# Wrapper by Skelp:

The GitLab repository: https://gitlab.com/Skelp/ApiPlant.CurrencyApi.Client

A NuGet package: https://www.nuget.org/packages/CurrencyApiClient/


IP GEO API

Get location by IP address

CURRENCY API

Get currency exhange rates