Free Currency API

https://freecurrencyapi.com/docs/
Admin
Free Currency API is a service that provides real-time and historical foreign exchange rates with...
Tokens:3,811
Snippets:22
Trust Score:8.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Authentication via GET Query Parameter (Bash)

Source: https://freecurrencyapi.com/docs/index

Demonstrates how to authenticate API requests using the 'apikey' as a GET query parameter in Bash.

```bash
curl "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY"
```

--------------------------------

### Authentication via GET Query Parameter (Python)

Source: https://freecurrencyapi.com/docs/index

Provides an example of authenticating API requests by appending the API key as a GET query parameter in Python using the requests library.

```python
import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY"

resp = requests.get(url)

print(resp.status_code)
```

--------------------------------

### Get Supported Currencies (GET Request)

Source: https://freecurrencyapi.com/docs/currencies

Demonstrates how to make a GET request to the Freecurrencyapi to retrieve a list of all supported currencies. It shows the base URL and the 'apikey' and 'currencies' query parameters. The 'currencies' parameter is optional and allows filtering by specific currency codes.

```bash
GET https://api.freecurrencyapi.com/v1/currencies?apikey=YOUR_API_KEY
```

```bash
GET https://api.freecurrencyapi.com/v1/currencies?apikey=YOUR_API_KEY&currencies=EUR,USD,CAD
```

--------------------------------

### Authentication via GET Query Parameter (JavaScript)

Source: https://freecurrencyapi.com/docs/index

Shows how to authenticate API requests by passing the API key as a GET query parameter in JavaScript using XMLHttpRequest.

```javascript
var oReq = new XMLHttpRequest();
oReq.addEventListener("load", function () { console.log(this.responseText); });
oReq.open("GET", "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY");
oReq.send();
```

--------------------------------

### Authentication via GET Query Parameter (PHP)

Source: https://freecurrencyapi.com/docs/index

Illustrates how to authenticate API requests by including the API key in the GET query parameter using PHP's cURL functions.

```php
$url = "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY";

$curl = curl_init($url);

$resp = curl_exec($curl);
var_dump($resp);
```

--------------------------------

### Authentication via HTTP Header (Python)

Source: https://freecurrencyapi.com/docs/index

Provides an example of authenticating API requests by setting the 'apikey' in the HTTP header using Python's requests library.

```python
import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.freecurrencyapi.com/v1/latest"

headers = CaseInsensitiveDict()
headers["apikey"] = "YOUR-APIKEY"

resp = requests.get(url, headers=headers)

print(resp.status_code)
```

--------------------------------

### GET /v1/currencies

Source: https://freecurrencyapi.com/docs/currencies

Retrieves a list of all supported currencies. You can optionally filter the results by providing a comma-separated list of currency codes.

```APIDOC
## GET /v1/currencies

### Description
Returns all supported currencies. You can optionally specify a list of currency codes to filter the results.

### Method
GET

### Endpoint
https://api.freecurrencyapi.com/v1/currencies

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API Key
- **currencies** (string) - Optional - A comma-separated list of currency codes (e.g., EUR,USD,CAD). If not provided, all available currencies will be returned.

### Request Example
```json
{
  "apikey": "YOUR_API_KEY",
  "currencies": "USD,EUR,GBP"
}
```

### Response
#### Success Response (200)
- **data** (object) - An object containing currency details for each requested currency.
  - **symbol** (string) - The currency symbol.
  - **name** (string) - The full name of the currency.
  - **symbol_native** (string) - The native symbol of the currency.
  - **decimal_digits** (number) - The number of decimal digits used for the currency.
  - **rounding** (number) - The rounding rules for the currency.
  - **code** (string) - The ISO currency code.
  - **name_plural** (string) - The plural name of the currency.

#### Response Example
```json
{
  "data": {
    "AED": {
      "symbol": "AED",
      "name": "United Arab Emirates Dirham",
      "symbol_native": "د.إ",
      "decimal_digits": 2,
      "rounding": 0,
      "code": "AED",
      "name_plural": "UAE dirhams"
    },
    "AFN": {
      "symbol": "Af",
      "name": "Afghan Afghani",
      "symbol_native": "؋",
      "decimal_digits": 0,
      "rounding": 0,
      "code": "AFN",
      "name_plural": "Afghan afghanis"
    }
  }
}
```

#### Error Response (400/401/403/404/500)
- **code** (string) - An error code.
- **message** (string) - A message describing the error.

#### Error Response Example
```json
{
  "code": "invalid_api_key",
  "message": "Invalid API key provided."
}
```
```

--------------------------------

### GET /v1/latest - Latest Currency Exchange Rates (Query Parameter)

Source: https://freecurrencyapi.com/docs/index

Retrieves the latest currency exchange rates by passing the API key as a query parameter.

```APIDOC
## GET /v1/latest

### Description
Retrieves the latest currency exchange rates. The API key can be passed as a query parameter named `apikey`.

### Method
GET

### Endpoint
https://api.freecurrencyapi.com/v1/latest

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY"
```

### Response
#### Success Response (200)
- The response contains a JSON object with the latest currency exchange rates.

#### Response Example
```json
{
  "data": {
    "USD": {
      "AED": 3.67,
      "AFN": 85.50,
      "ALL": 103.75
    }
  }
}
```
```

--------------------------------

### Sample JSON Response for Historical Exchange Rates

Source: https://freecurrencyapi.com/docs/historical

Provides an example of the JSON structure returned by the Historical Exchange Rates endpoint, showing exchange rates for a specific date against multiple currencies.

```json
{
    "data": {
        "2022-01-01": {
            "AED": 3.67306,
            "AFN": 91.80254,
            "ALL": 108.22904,
            "AMD": 480.41659,
            "...": "150+ more currencies"
        }
    }
}
```

--------------------------------

### GET /v1/latest - Latest Currency Exchange Rates (HTTP Header)

Source: https://freecurrencyapi.com/docs/index

Retrieves the latest currency exchange rates by passing the API key in the HTTP header.

```APIDOC
## GET /v1/latest

### Description
Retrieves the latest currency exchange rates. The API key can be passed as an HTTP header named `apikey`.

### Method
GET

### Endpoint
https://api.freecurrencyapi.com/v1/latest

### Parameters
#### Request Headers
- **apikey** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl "https://api.freecurrencyapi.com/v1/latest" \
    -H "apikey: YOUR-APIKEY"
```

### Response
#### Success Response (200)
- The response contains a JSON object with the latest currency exchange rates.

#### Response Example
```json
{
  "data": {
    "USD": {
      "AED": 3.67,
      "AFN": 85.50,
      "ALL": 103.75
    }
  }
}
```
```

--------------------------------

### GET /v1/status

Source: https://freecurrencyapi.com/docs/status

The Status endpoint returns your current API quota usage. Requests to this endpoint do not count against your quota or rate limit.

```APIDOC
## GET /v1/status

### Description
Returns your current API quota usage. Requests to this endpoint do not count against your quota or rate limit.

### Method
GET

### Endpoint
https://api.freecurrencyapi.com/v1/status

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API Key

### Response
#### Success Response (200)
- **quotas** (object) - An object containing quota information.
  - **month** (object) - An object containing monthly quota details.
    - **total** (integer) - The total quota for the month.
    - **used** (integer) - The amount of quota used this month.
    - **remaining** (integer) - The amount of quota remaining for the month.

### Response Example
```json
{
    "quotas": {
        "month": {
            "total": 300,
            "used": 71,
            "remaining": 229
        }
    }
}
```
```

--------------------------------

### GET /v1/historical

Source: https://freecurrencyapi.com/docs/historical

Fetches historical currency exchange rates for a specified date. You can filter by base currency and target currencies.

```APIDOC
## GET /v1/historical

### Description
Returns exchange rates for a given date. Data generally goes back to 1999.
For a range of historical data, please upgrade to currencyapi.com and use the /range endpoint.

### Method
GET

### Endpoint
https://api.freecurrencyapi.com/v1/historical

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API Key
- **date** (string) - Required - Start date to retrieve historical rates from (format: YYYY-MM-DD)
- **base_currency** (string) - Optional - The base currency to which all results are relative to. Defaults to USD.
- **currencies** (string) - Optional - A list of comma-separated currency codes to retrieve (e.g., EUR,USD,CAD). Defaults to all available currencies.

### Request Example
```json
{
  "apikey": "YOUR_API_KEY",
  "date": "2021-12-31",
  "base_currency": "EUR",
  "currencies": "USD,GBP,JPY"
}
```

### Response
#### Success Response (200)
- **data** (object) - An object containing the historical rates for the specified date.
  - **YYYY-MM-DD** (object) - An object where keys are currency codes and values are their exchange rates relative to the base currency.

#### Response Example
```json
{
  "data": {
    "2021-12-31": {
      "AED": 3.67306,
      "AFN": 91.80254,
      "ALL": 108.22904,
      "AMD": 480.41659,
      "...": "150+ more currencies"
    }
  }
}
```
```

--------------------------------

### Authentication via HTTP Header (Bash)

Source: https://freecurrencyapi.com/docs/index

Demonstrates how to authenticate API requests by setting the 'apikey' in the HTTP header using Bash.

```bash
curl "https://api.freecurrencyapi.com/v1/latest" \
    -H "apikey: YOUR-APIKEY"
```

--------------------------------

### Currencies Endpoint Sample Response (JSON)

Source: https://freecurrencyapi.com/docs/currencies

Provides a sample JSON response from the Freecurrencyapi's 'currencies' endpoint. The response includes detailed information for each currency, such as its symbol, name, native symbol, decimal digits, rounding rules, and currency code.

```json
{
    "data": {
        "AED": {
            "symbol": "AED",
            "name": "United Arab Emirates Dirham",
            "symbol_native": "د.إ",
            "decimal_digits": 2,
            "rounding": 0,
            "code": "AED",
            "name_plural": "UAE dirhams"
        },
        "AFN": {
            "symbol": "Af",
            "name": "Afghan Afghani",
            "symbol_native": "Af",
            "decimal_digits": 0,
            "rounding": 0,
            "code": "AFN",
            "name_plural": "Afghani"
        }
    }
}
```

--------------------------------

### Authentication via HTTP Header (JavaScript)

Source: https://freecurrencyapi.com/docs/index

Shows how to authenticate API requests by setting the 'apikey' in the HTTP header using JavaScript and XMLHttpRequest.

```javascript
var oReq = new XMLHttpRequest();
oReq.addEventListener("load", function () { console.log(this.responseText); });
oReq.open("GET", "https://api.freecurrencyapi.com/v1/latest");
oReq.setRequestHeader("apikey", "YOUR-APIKEY");
oReq.send();
```

--------------------------------

### Authentication via HTTP Header (PHP)

Source: https://freecurrencyapi.com/docs/index

Illustrates how to authenticate API requests by setting the 'apikey' in the HTTP header using PHP's cURL functions.

```php
$url = "https://api.freecurrencyapi.com/v1/latest";

$curl = curl_init($url);
$headers = array(
"apikey: YOUR-APIKEY",
);

$resp = curl_exec($curl);
var_dump($resp);
```

--------------------------------

### Sample JSON Response for Status Endpoint

Source: https://freecurrencyapi.com/docs/status

This JSON object represents a typical response from the Status Endpoint, detailing the user's monthly API usage quota, including total, used, and remaining requests.

```json
{
    "quotas": {
        "month": {
            "total": 300,
            "used": 71,
            "remaining": 229
        }
    }
}
```

--------------------------------

### Sample JSON Response for Latest Exchange Rates

Source: https://freecurrencyapi.com/docs/latest

This is a sample JSON response for the Latest Exchange Rates endpoint. It includes a 'data' object containing currency codes and their corresponding exchange rates. The default base currency is USD.

```json
{
    "data": {
        "AED": 3.67306,
        "AFN": 91.80254,
        "ALL": 108.22904,
        "AMD": 480.41659,
        "...": "150+ more currencies"
    }
}
```

--------------------------------

### Request Status Codes

Source: https://freecurrencyapi.com/docs/status-codes

Provides information on the HTTP status codes returned by the API, indicating success or failure of requests.

```APIDOC
## Request Status Codes

### Description

This section details the HTTP status codes returned by the API to signify the outcome of a request. A successful request is indicated by a 200 status code.

### Status Codes

- **200**: Success
- **401**: Invalid authentication credentials
- **403**: Insufficient permissions; upgrade plan required.
- **404**: Endpoint not found
- **422**: Validation error
- **429**: Rate limit exceeded; upgrade plan recommended.
- **500**: Internal Server Error; contact support@freecurrencyapi.com
```

--------------------------------

### Validation Errors

Source: https://freecurrencyapi.com/docs/status-codes

Details specific validation errors that may occur, along with the conditions that trigger them.

```APIDOC
## Validation Errors

### Description

This section outlines common validation errors encountered when using the API and provides guidance on how to resolve them.

### Error Types

- **Invalid currencies**: Indicates that one or more of the provided currency codes are not recognized. Refer to the `/currencies` endpoint for a valid list.
- **Invalid base_currency**: Signifies an unrecognized base currency. Use the `/currencies` endpoint to find valid currency codes.
- **Invalid date**: Occurs when the date format is incorrect. Ensure dates are in YYYY-MM-DD format.
- **Wrong format: value**: The provided value is not a number. Ensure numeric values are supplied where expected.
- **Chronological order issue (datetime_start)**: Indicates a problem with the chronological order of date parameters, likely with `datetime_start`.
```

--------------------------------

### Currency Data Snippet

Source: https://freecurrencyapi.com/docs/currencies

This snippet represents a portion of currency data, likely from a JSON response. It includes the native symbol, decimal digits, rounding rules, currency code, and the plural name for a currency.

```json
{
            "symbol_native": "؋",
            "decimal_digits": 0,
            "rounding": 0,
            "code": "AFN",
            "name_plural": "Afghan Afghanis"
        }
```

--------------------------------

### Latest Exchange Rates API

Source: https://freecurrencyapi.com/docs/latest

Retrieves the latest currency exchange rates relative to a specified base currency. By default, the base currency is USD.

```APIDOC
## GET /v1/latest

### Description
Returns the latest exchange rates. The default base currency is `USD`.

### Method
GET

### Endpoint
https://api.freecurrencyapi.com/v1/latest

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API Key
- **base_currency** (string) - Optional - The base currency to which all results are behaving relative to. By default all values are based on USD.
- **currencies** (string) - Optional - A list of comma-separated currency codes which you want to get (EUR,USD,CAD). By default all available currencies will be shown.

### Request Example
(No explicit request body for GET requests with query parameters)

### Response
#### Success Response (200)
- **data** (object) - Contains the exchange rates for each currency.
- **meta** (object) - Contains metadata, including `last_updated_at`.

#### Response Example
```json
{
    "data": {
        "AED": 3.67306,
        "AFN": 91.80254,
        "ALL": 108.22904,
        "AMD": 480.41659,
        "...": "150+ more currencies"
    }
}
```
```
Tokens:
Raw