Real time currency exchange rates with PHP - PHP Exchange Rate API package blog

How it all works

Source currency

Currency conversion

Conversion history

Other premium endpoints

Conclusion

The PHP Exchange Rate API package uses data provided by the currencyLayer service API. This is an API that provides currency information which is updated every 60 minutes for the free plan and up to every 60 seconds in the premium plans.

I like getting things for free, so this article will mostly focus on what is available to us with the free plan. I will also show you how to use the free plan to perform premium features like source switching and currency conversion. At the end of the article I will briefly discuss the other premium features of Time Frame Queries and Currency Change Queries.

If you will be following along with the code using the currency class, you will need your own access key which is available by signing up at https://currencylayer.com/product. Make sure you change the $apiKey property in the currencyLayer class to your unique key.

How it all works

The first thing we need to do is include the currencyLayer class and instantiate it.

error_reporting(E_ALL ^ E_NOTICE);
include('currency.class.php');
$currencyLayer = new currencyLayer();

The currencyLayer API has 5 different endpoints, of which we are mostly interested in the 'live' and 'historical' endpoints. For this example, we want live exchange rates so we will use the setEndpoint method on the next line of our code to specify the live endpoint.

$currencyLayer->setEndPoint('live');

The API supports 168 world currencies, for a full list of the codes and currencies you can visit https://currencylayer.com/currencies.

If we where to send our request now, all 168 currencies would be returned. We don't need them all, so we will limit the results to Bitcoins, Euro's and British Pounds by adding the following line...

$currencyLayer->setParam('currencies','BTC,EUR,GBP');

The parameter 'currencies' is supported by the API to limit currencies returned which will save you time and bandwidth by using it.

Notice that we are using the setParam method which specifies the parameter and value, which is a comma separated list of currency codes. The currency codes can be found by following the link for supported currencies provided above.

We are ready to send our request to the API and get back their response by using the getResponse method.

$currencyLayer->getResponse();

We can check to see if there was an error by checking the error property...

if( !empty($currencyLayer -> error -> code) ) {
   //handle the error
   echo 'The following error was reported - ' . $currencyLayer -> error -> text;
}

If the request was successful, then the response will contain the conversion rates to US Dollars from our requested currencies. The code for these rates are our source currency (USD) and conversion currency. So the code from USD to Euro's would be 'USDEUR' which we can display using the following line:

echo 'USD to EUR = '. $currencyLayer -> response -> quotes -> USDEUR;

Source currency

You may have noticed that we did not specify that our source currency was US Dollars. This is the default source currency used by currencyLayer and can only be changed if you have a premium plan.

If you purchased a premium plan you can easily change the source currency using the 'source' parameter, if you are using the free plan I will show you how to do a secondary conversion shortly.

Suppose we want the conversion rates from Euro's to Bitcoins and British Pounds.

Using a premium plan we can easily set up our request with the following lines:

$currencyLayer -> setParam( 'source', 'EUR');
$currencyLayer -> setParam( 'currencies', 'BTC,GBP');
$currencyLayer -> getResponse();

The response quotes would then be found in:

$currencyLayer -> response -> quotes -> EURBTC
$currencyLayer -> response -> quotes -> EURGBP

If we only have the free plan, then this will not be much use to us. We will receive an error that our plan does not support this feature. To get the results we are after, we will have to perform a secondary conversion based on conversion rates for the US Dollar. Don't worry, it is easier than it sounds.

$currencyLayer -> setParam( 'currencies', 'BTC,EUR,GBP');
$currencyLayer -> getResponse();
$EURBTC = $currencyLayer -> response -> quotes -> USDBTC / $currencyLayer -> response -> quotes -> USDEUR;
$EURGBP = $currencyLayer -> response -> quotes -> USDGBP / $currencyLayer -> response -> quotes -> USDEUR;

What we have done is gotten the conversion rates based on the default US Dollars and used those to figure the conversion rates for Euro's, which will be the values of our $EURBTC and $EURGBP variables.

Currency conversion

The currencyLayer API provides a 'convert' endpoint to calculate the conversion from one currency to another. This endpoint is only available in premium plans, however the class also provides a method for this conversion which can be used by us frugal users for free.

First we will look at conversion through the API for premium users:

$currencyLayer -> setEndPoint( 'convert' );
$currencyLayer -> setParam( 'from', 'USD' );
$currencyLayer -> setParam( 'to', 'AUD');
$currencyLayer -> setParam( 'amount', 10);
$currencyLayer -> getResponse();

This will convert 10 US Dollars to Australian Dollars which we can access through the following property values, the result will contain the conversion value.

$currencyLayer -> response -> query -> amount
$currencyLayer -> response -> query -> from
$currencyLayer -> response -> query -> to
$currencyLayer -> response -> result

To do this using the class, we would use the following code:

$currencyLayer -> setEndPoint( 'live' );
$currencyLayer -> setParam( 'currencies', 'AUD');
$currencyLayer -> getResponse();
$result = $currencyLayer -> convertCurrency( 10, 'AUD');

We are using the convertCurrency method with the amount and currency to convert to which will return our conversion value.

Conversion history

We can use the 'historical' endpoint to get the conversion rate at the close of the market for any supported currency as far back as the year 2000.

This endpoint works exactly like the live endpoint except that we also have to supply the date we want the conversion rate for. Our code would look something like this...

$currencyLayer -> setEndPoint( 'historical' );
$currencyLayer -> setParam( 'date', '2010-04-15' );
$currencyLayer -> setParam( 'currencies', 'EUR,GBP' );
$currencyLayer -> getResponse();

Note that the value for the 'date' parameter must be formatted as YYYY-MM-DD. In this example we are getting the conversion rates for Euro's and British Pounds on April 15th of 2010.

We would access the quotes exactly like we did with the live data...

$currencyLayer -> response -> quotes -> USDEUR

Other premium endpoints

The 'timeframe' endpoint is available to Professional and Enterprise premium plan users. This endpoint allows you to set a start_date and end_date which will return conversion rates for your specified currencies on each day between the start and end up to a maximum of 365 days.

You would access the quotes like this:

$currencyLayer -> response -> quotes -> 2010-04-15 -> USDEUR
$currencyLayer -> response -> quotes -> 2010-04-16 -> USDEUR

The 'change' endpoint is only available to Enterprise premium plan users. This endpoint will return the margin and percent change from a specified start_date (or the end of the previous day if not specified) and the most current conversion rate for one or more currencies.

You would access the returned values like this:

$currencyLayer -> response -> quotes -> USDEUR -> start_rate
$currencyLayer -> response -> quotes -> USDEUR -> end_rate
$currencyLayer -> response -> quotes -> USDEUR -> change
$currencyLayer -> response -> quotes -> USDEUR -> change_pct

Conclusion

As you can see, we can do quite a bit with our free access to the currencyLayer services since we can get both live and historical data. If you need more than 1,000 API accesses in a day then you will need to select the premium plan that best suits your needs.

If you want the quotes updated every 10 minutes then you will need the professional plan or updated every 60 seconds will require the enterprise plan.

While free is always nice, it is also important to remember that our clients or businesses that use the service extensively support our casual free use through premium plans.

If you like this article share with other developers that may want to know about a good currency conversion solution. If you have questions post a comment below.