My Company List

Currency Exchange Rate API Documentation

Endpoints

/v1/exchangerate/latest

Description:

Returns the latest currency exchange rate data. This info changes throughout the day.

Example request:

curl https://api.mycompanylist.com/v1/exchangerate/latest

Example response:

{
    "status": "success",
    "date": "2023-11-20",
    "base": "USD",
    "rates": {
        "AED": {
            "rate": 3.6728828611,
            "observation_time": "2023-11-20T11:00:00.000Z",
            "source": "bnro"
        },
        "AFN": {
            "rate": 69.0579,
            "observation_time": "2023-11-20T19:00:00.000Z",
            "source": "gaf"
        },
        "AMD": {
            "rate": 402.2006290109,
            "observation_time": "2023-11-20T13:00:00.000Z",
            "source": "cbr"
        },        ...
    }
}

URL Parameters:

  • base
    • Description: Base currency. Rate is expressed as the number of that currency you could buy with 1 unit of base currency.
    • Default: USD
    • Possible Values: any symbol within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/latest?base=EUR
  • format
    • Description: The structure of the data in the response.
    • Default: json
    • Possible Values: json, csv, xml
    • Example: /v1/exchangerate/latest?format=csv
  • symbols
    • Description: comma separated list of symbols to include in the response. ‘*’ indicates all symbols available.
    • Default: ‘*’
    • Possible Values: comma separated list of any symbols within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/latest?symbols=EUR,USD,CAD
  • sources
    • Description: comma separated list of source short names to include in the response, in order of priority.
    • Default: imf,ecb,boe,bac,rba,snb,bnro,boi,nbu,cbr,bcb,cbn,gaf,float_rates
    • Possible Values: comma separated list of any source short names within ‘/v1/exchangerate/sources‘
    • Example: /v1/exchangerate/latest?sources=imf,bac,gaf
    • Notes: sources not included in this field will not be included in results, even if that means certain requested symbols are not in results.
  • up_to_days_before
    • Description: Number of days prior an observed conversion rate is considered valid for this query.
    • Default: 4
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/latest?up_to_days_before=0
    • Notes: Consider if today is 2023-11-05, a Sunday, and if using the source ‘bcb’, which doesn’t update over the weekend, a value of at least 3 will return the value from last Friday. The default of 4 allows weekends + up to one business holiday.
  • max_sources_per_symbol
    • Description: Max number of sources per symbol
    • Default: 1
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/latest?max_sources_per_symbol=10
    • Notes: a value of > 1 changes the structure of the json response; ‘source‘ becomes a key within ‘symbol‘.
  • observation_time_selection
    • Description: Whether to get the earliest or latest observation today
    • Default: latest
    • Possible Values: latest, earliest
    • Example: /v1/exchangerate/observation_time_selection=earliest
  • decimals
    • Description: Number of digits after the ‘.’ at most for ‘rate’.
    • Default: 16
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/latest?decimals=5
  • pretty_print
    • Description: when format is JSON, include ‘\n‘ in output to make it more human readable.
    • Default: true
    • Possible Values: true, false
    • Example: /v1/exchangerate/latest?pretty_print=false
  • show_query
    • Description: Show the SQL query that yields this result. This can be used with the ‘/v1/exchangerate/query‘ endpoint.
    • Default: false
    • Possible Values: false, true
    • Example: /v1/exchangerate/latest?show_query=true

Notes:

The response of this endpoint changes throughout the day. If your goal is to get the most accurate exchange rates possible and it doesn’t have to be the absolute latest, you are better off getting historical rates that are no longer updating.

/v1/exchangerate/<date YYYY-MM-DD>

Description:

The exchange rates from a specific date.

Example request:

curl https://api.mycompanylist.com/v1/exchangerate/2023-11-04

Example response:

{
    "status": "success",
    "date": "2023-11-04",
    "base": "USD",
    "rates": {
        "AED": {
            "rate": 3.6660014268,
            "observation_time": "2023-11-04T23:55:01.000Z",
            "source": "float_rates"
        },
        "AFN": {
            "rate": 73.445,
            "observation_time": "2023-11-04T11:30:00.000Z",
            "source": "gaf"
        },
        "AMD": {
            "rate": 401.7694495046,
            "observation_time": "2023-11-04T23:55:01.000Z",
            "source": "float_rates"
        },
        ...
    }
}

URL Parameters:

  • base
    • Description: Base currency. Rate is expressed as the number of that currency you could buy with 1 unit of base currency.
    • Default: USD
    • Possible Values: any symbol within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/2023-11-01?base=EUR
  • format
    • Description: The structure of the data in the response.
    • Default: json
    • Possible Values: json, csv, xml
    • Example: /v1/exchangerate/2023-11-01?format=csv
  • symbols
    • Description: comma separated list of symbols to include in the response. ‘*’ indicates all symbols available.
    • Default: ‘*’
    • Possible Values: comma separated list of any symbols within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/2023-11-01?symbols=EUR,USD,CAD
  • sources
    • Description: comma separated list of source short names to include in the response, in order of priority.
    • Default: imf,ecb,boe,bac,rba,snb,bnro,boi,nbu,cbr,bcb,cbn,gaf,float_rates
    • Possible Values: comma separated list of any source short names within ‘/v1/exchangerate/sources‘
    • Example: /v1/exchangerate/2023-11-01?sources=imf,bac,gaf
    • Notes: sources not included in this field will not be included in results, even if that means certain requested symbols are not in results.
  • up_to_days_before
    • Description: Number of days prior an observed conversion rate is considered valid for this query.
    • Default: 4
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/2023-11-01?up_to_days_before=0
    • Notes: Consider if today is 2023-11-05, a Sunday, and if using the source ‘bcb’, which doesn’t update over the weekend, a value of at least 3 will return the value from last Friday. The default of 4 allows weekends + up to one business holiday.
  • max_sources_per_symbol
    • Description: Max number of sources per symbol
    • Default: 1
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/2023-11-01?max_sources_per_symbol=10
    • Notes: a value of > 1 changes the structure of the json response; ‘source‘ becomes a key within ‘symbol‘.
  • observation_time_selection
    • Description: Whether to get the earliest or latest observation for the selected date
    • Default: earliest
    • Possible Values: latest, earliest
    • Example:/v1/exchangerate/2023-11-01?observation_time_selection=latest
  • decimals
    • Description: Number of digits after the ‘.’ at most for ‘rate’.
    • Default: 16
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/2023-11-01?decimals=5
  • pretty_print
    • Description: when format is JSON, include ‘\n‘ in output to make it more human readable.
    • Default: true
    • Possible Values: true, false
    • Example: /v1/exchangerate/2023-11-01?pretty_print=false
  • show_query
    • Description: Show the SQL query that yields this result. This can be used with the ‘/v1/exchangerate/query‘ endpoint.
    • Default: false
    • Possible Values: false, true
    • Example: /v1/exchangerate/2023-11-01?show_query=true

Notes:

Similar to ‘/v1/exchangerate/latest‘ the rates in the response update throughout the day for dates within 1-2 days of present, depending on lag between observation and publishing for the source(s) you are using.

/v1/exchangerate/<start_date YYYY-MM-DD>/<end_date YYYY-MM-DD>

Description:

The rates between two dates. Instead of a date, you can also input ‘*’ to mean the earliest or latest date possible.

Example request:

curl https://api.exchangerate.pro/v1/exchangerate/2023-11-01/2023-11-04

Example response:

{
    "status": "success",
    "start_date": "2023-11-01",
    "end_date": "2023-11-04",
    "base": "USD",
    "rates": {
        "2023-11-04": {
            "AED": {
                "rate": 3.6660014268,
                "observation_time": "2023-11-04T23:55:01.000Z",
                "source": "float_rates"
            },
            ...
        },
        "2023-11-03": {
            "AED": {
                "rate": 3.6729589429,
                "observation_time": "2023-11-03T11:00:00.000Z",
                "source": "bnro"
            },
            ...
        },
        ...
    }
}

URL Parameters:

  • aggregation
    • Description: Group exchange rates by a unit of time.
    • Default: day
    • Possible Values: day, week, month, quarter, year, decade, century, millennium
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?aggregation=week
  • base
    • Description: Base currency. Rate is expressed as the number of that currency you could buy with 1 unit of base currency.
    • Default: USD
    • Possible Values: any symbol within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?base=EUR
  • format
    • Description: The structure of the data in the response.
    • Default: json
    • Possible Values: json, csv, xml
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?format=csv
  • symbols
    • Description: comma separated list of symbols to include in the response. ‘*’ indicates all symbols available.
    • Default: ‘*’
    • Possible Values: comma separated list of any symbols within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?symbols=EUR,USD,CAD
  • sources
    • Description: comma separated list of source short names to include in the response, in order of priority.
    • Default: imf,ecb,boe,bac,rba,snb,bnro,boi,nbu,cbr,bcb,cbn,gaf,float_rates
    • Possible Values: comma separated list of any source short names within ‘/v1/exchangerate/sources‘
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?sources=imf,bac,gaf
    • Notes: sources not included in this field will not be included in results, even if that means certain requested symbols are not in results.
  • up_to_days_before
    • Description: Number of days prior an observed conversion rate is considered valid for this query.
    • Default: 4
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?up_to_days_before=0
    • Notes: values from ‘up_to_days_before‘ days before ‘start_date‘ will appear within ‘start_date‘.
  • max_sources_per_symbol
    • Description: Max number of sources per symbol
    • Default: 1
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?max_sources_per_symbol=10
    • Notes: a value of > 1 changes the structure of the json response; ‘source‘ becomes a key within ‘symbol‘.
  • observation_time_selection
    • Description: Whether to get the earliest or latest observation for the selected date
    • Default: earliest
    • Possible Values: latest, earliest
    • Example:/v1/exchangerate/2023-11-01/2023-11-04?observation_time_selection=latest
  • decimals
    • Description: Number of digits after the ‘.’ at most for ‘rate’.
    • Default: 16
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?decimals=5
  • pretty_print
    • Description: when format is JSON, include ‘\n‘ in output to make it more human readable.
    • Default: true
    • Possible Values: true, false
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?pretty_print=false
  • show_query
    • Description: Show the SQL query that yields this result. This can be used with the ‘/v1/exchangerate/query‘ endpoint.
    • Default: false
    • Possible Values: false, true
    • Example: /v1/exchangerate/2023-11-01/2023-11-04?show_query=true

Notes:

If start_date is after end_date, they will be swapped.

/v1/exchangerate/all

Pull all exchange rate data. This is equivalent to ‘/v1/exchangerate/*/*‘.

Example request:

curl https://api.mycompanylist.com/v1/exchangerate/all

Example response:

{
    "status": "success",
    "start_date": "2000-01-01",
    "end_date": "2023-11-05",
    "base": "USD",
    "rates": {
        "2023-11-04": {
            "AED": {
                "rate": 3.6660014268,
                "observation_time": "2023-11-04T23:55:01.000Z",
                "source": "float_rates"
            },
            ...
        },
        "2023-11-03": {
            "AED": {
                "rate": 3.6729589429,
                "observation_time": "2023-11-03T11:00:00.000Z",
                "source": "bnro"
            },
            ...
        },
        ...
    }
}

URL Parameters:

  • aggregation
    • Description: Group exchange rates by a unit of time.
    • Default: day
    • Possible Values: day, week, month, quarter, year, decade, century, millennium
    • Example: /v1/exchangerate/all?aggregation=week
  • base
    • Description: Base currency. Rate is expressed as the number of that currency you could buy with 1 unit of base currency.
    • Default: USD
    • Possible Values: any symbol within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/all?base=EUR
  • format
    • Description: The structure of the data in the response.
    • Default: json
    • Possible Values: json, csv, xml
    • Example: /v1/exchangerate/all?format=csv
  • symbols
    • Description: comma separated list of symbols to include in the response. ‘*’ indicates all symbols available.
    • Default: ‘*’
    • Possible Values: comma separated list of any symbols within ‘/v1/exchangerate/currencies‘.
    • Example: /v1/exchangerate/all?symbols=EUR,USD,CAD
  • sources
    • Description: comma separated list of source short names to include in the response, in order of priority.
    • Default: imf,rab,bac,ecb,bnro,snb,cbr,nbu,boi,cbn,boe,gaf,bcb,float_rates
    • Possible Values: comma separated list of any source short names within ‘/v1/exchangerate/sources‘
    • Example: /v1/exchangerate/all?sources=imf,bac,gaf
    • Notes: sources not included in this field will not be included in results, even if that means certain requested symbols are not in results.
  • up_to_days_before
    • Description: Number of days prior an observed conversion rate is considered valid for this query.
    • Default: 4
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/all?up_to_days_before=0
    • Notes: values from ‘up_to_days_before‘ days before ‘start_date‘ will appear within ‘start_date‘.
  • max_sources_per_symbol
    • Description: Max number of sources per symbol
    • Default: 1
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/all?max_sources_per_symbol=10
    • Notes: a value of > 1 changes the structure of the json response; ‘source‘ becomes a key within ‘symbol‘.
  • observation_time_selection
    • Description: Whether to get the earliest or latest observation for the selected date
    • Default: earliest
    • Possible Values: latest, earliest
    • Example:/v1/exchangerate/all?observation_time_selection=latest
  • decimals
    • Description: Number of digits after the ‘.’ at most for ‘rate’.
    • Default: 16
    • Possible Values: a positive integer
    • Example: /v1/exchangerate/all?decimals=5
  • pretty_print
    • Description: when format is JSON, include ‘\n‘ in output to make it more human readable.
    • Default: true
    • Possible Values: true, false
    • Example: /v1/exchangerate/all?pretty_print=false
  • show_query
    • Description: Show the SQL query that yields this result. This can be used with the ‘/v1/exchangerate/query‘ endpoint.
    • Default: false
    • Possible Values: false, true
    • Example: /v1/exchangerate/all?show_query=true

/v1/exchangerate/currencies

Example request:

curl https://api.mycompanylist.com/v1/exchangerate/currencies

Example response:

{
    "status": "success",
    "num_symbols": 155,
    "symbols": {
        "AED": {
            "sources": [
                "imf",
                "bnro",
                "cbr",
                ...
            ]
        },
        "AFN": {
            "sources": [
                "gaf",
                "float_rates"
            ]
        },
        "ALL": {
            "sources": [
                "float_rates"
            ]
        },
        ...
    }
}

URL Parameters:

  • format
    • Description: The structure of the data in the response.
    • Default: json
    • Possible Values: json, csv
    • Example: /v1/currencies?format=csv
  • symbols
    • Description: comma separated list of symbols to include in the response. ‘*’ indicates all symbols available.
    • Default: ‘*’
    • Possible Values: comma separated list of any symbols within ‘/v1/currencies‘.
    • Example: /v1/currencies?symbols=EUR,USD,CAD
  • sources
    • Description: comma separated list of source short names to include in the response, in order of priority.
    • Default: imf,ecb,boe,bac,rba,snb,bnro,boi,nbu,cbr,bcb,cbn,gaf,float_rates
    • Possible Values: comma separated list of any source short names within ‘/v1/sources‘
    • Example:/v1/currencies?sources=imf,ecb,bac,gaf
    • Notes: currencies that are only from sources not included in this field will not be included in results.
  • pretty_print
    • Description: when format is JSON, include ‘\n‘ in output to make it more human readable.
    • Default: true
    • Possible Values: true, false
    • Example: /v1/currencies?pretty_print=false

/v1/exchangerate/sources

Example request:

curl https://api.mycompanylist.com/v1/exchangerate/sources

Example response:

{
    "status": "success",
    "currencies": {
        "imf": {
            "name": "International Monetary Fund",
            "relative_currency": "USD",
            "url": "https://www.imf.org/external/np/fin/data/rms_rep.aspx?tsvflag=Y",
            "is_dst": true,
            "default_precedence": 0,
            "num_symbols": 38,
            "symbols": [
                "AED",
                "AUD",
                "BND",
                ...
            ]
        },
        "ecb": {
            "name": "European Central Bank",
            "relative_currency": "EUR",
            "url": "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml",
            "is_dst": true,
            "default_precedence": 1,
            "num_symbols": 31,
            "symbols": [
                "AUD",
                "BGN",
                "BRL",
                ...
            ]
        },
        "boe": {
            "name": "Bank Of England",
            "relative_currency": "GBP",
            "url": "https://www.bankofengland.co.uk/boeapps/database/Rates.asp?into=GBP",
            "is_dst": true,
            "default_precedence": 2,
            "num_symbols": 26,
            "symbols": [
                "AUD",
                "CAD",
                "CHF",
                ...
            ]
        },
        ...
    }
}

URL Parameters:

  • format
    • Description: The structure of the data in the response.
    • Default: json
    • Possible Values: json, csv
    • Example: /v1/sources?format=csv
  • symbols
    • Description: comma separated list of symbols to include in the response. ‘*’ indicates all symbols available.
    • Default: ‘*’
    • Possible Values: comma separated list of any symbols within ‘/v1/currencies‘.
    • Example: /v1/sources?symbols=EUR,USD,CAD
    • Note:
  • sources
    • Description: comma separated list of source short names to include in the response, in order of priority.
    • Default: imf,ecb,boe,bac,rba,snb,bnro,boi,nbu,cbr,bcb,cbn,gaf,float_rates
    • Possible Values: comma separated list of any source short names within ‘/v1/sources‘
    • Example:/v1/sources?sources=imf,ecb,bac,gaf
  • pretty_print
    • Description: when format is JSON, include ‘\n‘ in output to make it more human readable.
    • Default: true
    • Possible Values: true, false
    • Example: /v1/sources?pretty_print=false

Errors

  • 404: Not Found
    • You have requested a URL that does not match any of the endpoints.
  • 400: Bad Request
    • You have requested a URL that includes a YYYY-MM-DD formatted date and the input is not a valid date (ex: 2023-30-01 — there is no 30th month, 2023-02-29 — there is the 29th of February in 2023)
  • Errors as a response header and json parameter
    • If a parameter input was not within the list of allowed values, or the parameter was not within the list of expected parameters, this will appear within the response header ‘X-Error’ as well as within the json response body under the key ‘error’. A response is still given with the data that was most likely intended to be queried.

Rate Limits

There are no rate limits. Please use freely.

Posted

in

by

Elliot MacNeille

Tags:

,

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *