Overview

There is no installation process when using the REST JSON/XML API. Just start using the REST services by making HTTP GET requests to the Global Exchange API server. You can make requests from any client that can make HTTP requests. That could be a browser, a mobile app, or a desktop application. You name it.

For instance, to get information on all supported currencies, just send a GET request to the currencies resource.

Example

Get all supported currencies:

http://globalexchangeapi.com/api/currencies

To get information on a specific currency, add a unique identifier to the request that explicitly or implicitly identify the currency. Currencies are explicitly identified by an ISO 4217 currency code or number.

Example

Get currency information on US dollar (ISO 4217 currency code USD):

http://globalexchangeapi.com/api/currencies/USD

The currency can also be implied from a country of the world.

Example

Get currency information on the currency used in Colombia (ISO 3166 country code CO):

http://globalexchangeapi.com/api/currencies/CO

The country can be implied from an IP address.

Example

Get currency information on the currency used by the country related to IP address 195.215.103.254:

http://globalexchangeapi.com/api/currencies/195.215.103.254

Yet again, the IP address can be that of the remote client. The value 0 (zero) is used for that. In requests, the 0 (zero) identifier is translated into the IP address of the remote client.

Example

Get currency information on the currency used by the country related to your IP address:

http://globalexchangeapi.com/api/currencies/0

Identifiers

Most request to the JSON/XML API require a country or currency identifier to identify the requested resource.

Country Identifiers

Countries can be identified either explicitly from a country code or implicitly from a location in the world

  • explicitly from a two-character ISO 3166 country code, e.g. US, DK, or CO.
  • implicitly from an IP version 4 address, e.g. 24.252.11.4 (US), 195.215.103.254 (DK), or 66.231.64.17 (CO).
  • implicitly from the country of the remote client with 0 (zero).

Currency Identifiers

Currencies can be identified either explicitly from a currency code or implicitly from a location in the world

  • explicitly from a three-character ISO 4217 currency code, e.g. USD, DKK, or COP.
  • explicitly from a three-digit ISO 4217 currency code, e.g. 840, 208, or 170.
  • implicitly from a two-character ISO 3166 country code, e.g. US, DK, or CO.
  • implicitly from a culture name, e.g. en-US, da-DK, or es-CO.
  • implicitly from an IP version 4 address, e.g. 24.252.11.4 (US), 195.215.103.254 (DK), or 66.231.64.17 (CO).
  • implicitly from the country of the remote client with 0 (zero).

Resources

The GET requests all query information on the resources that the JSON/XML API provides. All URLs represents a resource located on the Global Exhange API server. The accepted URLs follow this format:

http://globalexchangeapi.com/api/{resource}/[{id}]?[{query}]

The resource part is mandatory. It is the type of information you want to get from the server. If the resource is a collection, like the country and currencies resources, requesting just the resource will return the entire collection. The id is for identifying a single piece of resource to get. In some cases the resource request must be further refined using query string arguments.

Exchange

Use the exchange resource to exchange an amount from one currency to another. Specify an amount, a currency to exchange from, and a currency to exchange to.

Example

Convert 123.45 USD to the preferred currency of the remote client:

http://globalexchangeapi.com/api/exchange?amount=123.45&from=usd&to=0

The from and to arguments can be any currency identifier.

Countries

The countries resource provides information about supported countries.

Example

Get information on Denmark:

http://globalexchangeapi.com/api/countries/DK

The id argument can be any country identifier. If omitted, then all known countries are returned.

Currencies

The currencies resource provides information about supported currencies.

Example

Get information on the currency used in Denmark:

http://globalexchangeapi.com/api/currencies/DK

The id argument can be any currency identifier. If omitted, then all known currencies are returned.

IP Address

The ipaddress resource does not accept any identifiers. It simply returns your host IP address

Example

Get your IP address:

http://globalexchangeapi.com/api/ipaddress

Content Negotiation

If you try to enter one of the examples above into your browser, the response you receive will either be in XML or JSON depending on your browser settings. The browser adds an Accept header to your request, which specifies the preferred response representation.

Content negotiation is a mechanism that makes it possible to serve different representations of a resource at the same URI. It is up to you as a client to inform the server which representation you accept in the response. With the JSON/XML API there are three ways to do that.

Request Accept Header

The Request Accept HTTP header lists accepted MIME types. To get the response in either JSON or XML, make application/json or application/xml the accepted MIME type.

Example

Get all supported countries using request accept header for content negotiation:

http://globalexchangeapi.com/api/countries

Query String Parameter

Add a format=json or format=xml query string parameter to the request.

Example

Get all supported countries in XML by adding a format=xml query string parameter:

http://globalexchangeapi.com/api/countries?format=xml

URI Path Extension

Extent the URI path with .json or .xml.

Example

Get all supported countries in XML by extending the URI path with .xml:

http://globalexchangeapi.com/api/countries.xml

Subscription

The first month is free. After the first month, you must subscribe to the API to get a subscription token. The subscription token must be added to all requests in a token query string argument. If you require less than 1000 request/month the API continues to be free. Just make a free subscription.

Example

http://globalexchangeapi.com/api/ipaddress?token=CTS4CNLDL5V59PT4