Available in all plans

Cross Rates Matrix

On this page, we’ll dive into the matrix endpoint you can use to get every cross rate between up to 25 currencies in one request, as JSON or as a ready-made CSV table.

Instead of requesting /latest once per base currency, one request returns the full table: the price of every currency in every other one. Typical uses are currency tables on websites, price lists in several currencies and spreadsheets.

GET/v3/matrix

Cross Rates Matrix

Returns one row per currency in currencies: data.EUR.USD is the price of 1 EUR in USD. Without date you get the latest rates at your plan’s update interval.

Required attributes

Name
currencies
Type
string
Description
2 to 25 comma separated currency codes (USD,EUR,GBP) Alternatively you can provide a GET parameter array like so: currencies[]=USD&currencies[]=EUR Rows and columns keep this order

Optional attributes

Name
date
Type
string
Description
The rates at the close of this past day (format: 2021-12-31)
Name
precision
Type
integer
Description
Round every rate to this many decimals (0 to 10) By default values carry up to 10 decimals
Name
format
Type
string
Description
json (default), csv or xlsx. The CSV is the table itself: a header base_currency,USD,EUR,GBP and one row per base currency xlsx gives the same table as an Excel workbook, see Excel downloads

Response Properties

Name
meta.last_updated_at
Type
string
Description
The update time of the rates, as a datetime string
Name
meta.currencies
Type
array
Description
The currencies of the rows and columns, in order
Name
data.BASE.QUOTE
Type
float
Description
The price of one unit of BASE in QUOTE. 1 where both are the same currency, null where a currency has no rate

A request costs one request of your quota, however many currencies it holds. Fewer than 2 or more than 25 currencies return a 422.

CSV table

Matrix as CSV

curl -G https://api.currencyapi.com/v3/matrix \
    -d currencies=USD,EUR,GBP \
    -d format=csv \
    -H "apikey: YOUR-API-KEY"

Response (text/csv)

base_currency,USD,EUR,GBP
USD,1,0.918456,0.786123
EUR,1.0887771,1,0.8559168
GBP,1.2720671,1.1683413,1

Request

GET

/v3/matrix

curl -G https://api.currencyapi.com/v3/matrix \
    -d currencies=USD,EUR,GBP \
    -H "apikey: YOUR-API-KEY"

Response

{
    "meta": {
        "last_updated_at": "2023-06-23T10:15:59Z",
        "currencies": ["USD", "EUR", "GBP"]
    },
    "data": {
        "USD": {
            "USD": 1,
            "EUR": 0.918456,
            "GBP": 0.786123
        },
        "EUR": {
            "USD": 1.0887771,
            "EUR": 1,
            "GBP": 0.8559168
        },
        "GBP": {
            "USD": 1.2720671,
            "EUR": 1.1683413,
            "GBP": 1
        }
    }
}