SWOP GraphQL API

Quickstart

The easiest way to get started, is to use the GraphQL Playground. Login or register a free account to get access.

Authentication

The SWOP API uses API Keys to authenticate requests. To authenticate a request, you can either pass your API Key as a query parameter or as a request header.

Authentication by Query Parameter

Pass the API Key using the query parameter api-key

Configure the endpoint with the query param:

  
    
    https://swop.cx/graphql?api-key=<your-api-key-here>
Authentication by Request Header

Pass the API Key using the Authorization request header with type ApiKey in your GraphQL client:

  
    
    Authorization: ApiKey <your-api-key-here>

Endpoint

You can access the GraphQL endpoint using this URL:

  
    
      https://swop.cx/graphql

The endpoint accepts POST requests with a JSON encoded body

GraphQL Queries

The following resources can be queried

latest

The latest query returns the most recent exchange rates.

Query: 

  
    
      query LatestEuro {
        latest(baseCurrency: "EUR", quoteCurrencies: ["USD", "CHF", "HKD"]) {
          date
          baseCurrency
          quoteCurrency
          quote
        }
      }

Arguments
latest
name required description
baseCurrency no ISO 4217 Currency code. Default is EUR.
quoteCurrencies no List of ISO 4217 currency codes. By default, all quote currencies are returned.

Response: List of rates for today 

  
    
      {
        "data": {
          "latest": [
            {
              "date": "2020-04-08",
              "baseCurrency": "EUR",
              "quoteCurrency": "CHF",
              "quote": 1.0557
            },
            {
              "date": "2020-04-08",
              "baseCurrency": "EUR",
              "quoteCurrency": "HKD",
              "quote": 8.4277
            },
            {
              "date": "2020-04-08",
              "baseCurrency": "EUR",
              "quoteCurrency": "USD",
              "quote": 1.0871
            }
          ]
        }
      }

historical

The historical query returns exchange rates for a specific date in the past.

Query: 

  
    
      query AprilFourthUSD {
        historical(date: "2020-04-04", baseCurrency: "USD", quoteCurrencies: ["EUR", "GBP"]) {
          date
          baseCurrency
          quoteCurrency
          quote
        }
      }

Arguments
historical
name required description
date yes ISO 8601 date (YYYY-MM-DD, between 1999-01-04 and today). Default is today.
baseCurrency no ISO 4217 Currency code. Default is EUR.
quoteCurrencies no List of ISO 4217 currency codes. By default, all quote currencies are returned.

Response: List of rates for given date 

  
    
      {
        "data": {
          "historical": [
            {
              "date": "2020-04-08",
              "baseCurrency": "USD",
              "quoteCurrency": "EUR",
              "quote": 0.919879
            },
            {
              "date": "2020-04-08",
              "baseCurrency": "USD",
              "quoteCurrency": "GBP",
              "quote": 0.809015
            }
          ]
        }
      }

timeSeries

The timeSeries query returns exchange rates time series for a given time range.

Query: 

  
    
      query {
        timeSeries(dateFrom: "2000-01-01", dateTo: "2000-01-03", baseCurrency: "EUR", quoteCurrencies: ["USD", "GBP"]) {
          baseCurrency
          quoteCurrency
          rates {
            date
            quote
          }
        }
      }

Arguments
timeSeries
name required description
dateFrom yes ISO 8601 date (YYYY-MM-DD). Must be between 1999-01-04 and today.
dateTo yes ISO 8601 date (YYYY-MM-DD). Must be between 1999-01-04 and today.
baseCurrency no ISO 4217 Currency code. Default is EUR.
quoteCurrencies no List of ISO 4217 currency codes. By default, all quote currencies are returned.

Query Limit: The timeSeries query is limited to 4000 rates per request. This allows to query a time range of:

  • Single quoteCurrency: 10 years
  • Multiple quoteCurrencies: 10 years divided by number of quote currencies, eg. 2 years for 5 quote currencies
  • All quoteCurrencies: 1 month
  • If rate meta data + calculation paths are queried, the allowed rate limit is 400.

Response: List of currency pairs, each with a list of quotes by date 

  
    
      {
        "data": {
          "timeSeries": [
            {
              "baseCurrency": "EUR",
              "quoteCurrency": "GBP",
              "quotes": [
                {
                  "date": "2000-01-01",
                  "quote": 0.6217
                },
                {
                  "date": "2000-01-02",
                  "quote": 0.6246
                },
                {
                  "date": "2000-01-03",
                  "quote": 0.6296
                }
              ]
            },
            {
              "baseCurrency": "EUR",
              "quoteCurrency": "USD",
              "quotes": [
                {
                  "date": "2000-01-01",
                  "quote": 1.0046
                },
                {
                  "date": "2000-01-02",
                  "quote": 1.009
                },
                {
                  "date": "2000-01-03",
                  "quote": 1.0305
                }
              ]
            }
          ]
        }
      }

fluctuation

The fluctuation query returns the fluctuation of rates between two dates.

Query: 

  
    
      query {
        fluctuation(dateFrom: "2019-01-01", dateTo: "2020-01-01", baseCurrency:"GBP", quoteCurrencies: ["EUR","USD","CHF"]) {
          baseCurrency
          quoteCurrency
          dateFrom
          dateTo
          fluctuation
          fluctuationPercent
          rateFrom {
            quote
          }
          rateTo {
            quote
          }
        }
      }

Arguments
fluctuation
name required description
dateFrom yes ISO 8601 date (YYYY-MM-DD). Must be between 1999-01-04 and today.
dateTo yes ISO 8601 date (YYYY-MM-DD). Must be between 1999-01-04 and today.
baseCurrency no ISO 4217 Currency code. Default is EUR.
quoteCurrencies no List of ISO 4217 currency codes. By default, all quote currencies are returned.

Response: List currency pairs with fluctuation between given dates 

  
    
      {
        "data": {
          "fluctuation": [
            {
              "baseCurrency": "GBP",
              "quoteCurrency": "CHF",
              "dateFrom": "2019-01-01",
              "dateTo": "2020-01-01",
              "fluctuation": 0.017704,
              "fluctuationPercent": 1.408045,
              "rateFrom": {
                "quote": 1.25734
              },
              "rateTo": {
                "quote": 1.275044
              }
            },
            {
              "baseCurrency": "GBP",
              "quoteCurrency": "EUR",
              "dateFrom": "2019-01-01",
              "dateTo": "2020-01-01",
              "fluctuation": 0.058532,
              "fluctuationPercent": 5.245363,
              "rateFrom": {
                "quote": 1.115871
              },
              "rateTo": {
                "quote": 1.174403
              }
            },
            {
              "baseCurrency": "GBP",
              "quoteCurrency": "USD",
              "dateFrom": "2019-01-01",
              "dateTo": "2020-01-01",
              "fluctuation": 0.04116,
              "fluctuationPercent": 3.223314,
              "rateFrom": {
                "quote": 1.276953
              },
              "rateTo": {
                "quote": 1.318114
              }
            }
          ]
        }
      }

convert

The convert query converts an amount from baseCurrency to multiple quoteCurrencies currencies.

Query: 

  
    
      query ConvertToGBP {
        convert(amount: 12.34, baseCurrency: "USD", quoteCurrencies: ["GBP"], date: "2020-04-08") {
          date
          baseCurrency
          quoteCurrency
          baseAmount
          quoteAmount
        }
      }

Arguments
convert
name required description
amount yes Decimal amount in base currency.
baseCurrency yes ISO 4217 Currency code. Default is EUR.
quoteCurrencies no List of ISO 4217 currency codes. By default, all quote currencies are returned.
date no ISO 8601 date (YYYY-MM-DD, between 1999-01-04 and today). Default is today.

Response: Single conversion 

  
    
    {
      "data": {
        "convert": [
          {
            "date": "2020-04-08",
            "baseCurrency": "USD",
            "quoteCurrency": "GBP",
            "baseAmount": 12.34,
            "quoteAmount": 9.98
          }
        ]
      }
    }

currencies

The currencies query returns information about the available currencies.

Query: 

  
    
      query USDInfo {
        currencies(currencyCodes: ["USD"]) {
          code
          name
          numericCode
          decimalDigits
          active
        }
      }

Arguments
currencies
name required description
currencyCodes no List of ISO 4217 currency codes. By default, all currencies are returned.
includeHistorical no Boolean, include historical currencies for which we don't have current rates. Default false.

Response: List of currencies 

  
    
      {
        "data": {
          "currencies": [
            {
              "code": "SGD",
              "numeric_code": "702",
              "decimal_digits": 2,
              "name": "Singapore dollar",
              "active": true
            },
            {
              "code": "USD",
              "numeric_code": "840",
              "decimal_digits": 2,
              "name": "United States dollar",
              "active": true
            },
            {
              "code": "ZMK",
              "numericCode": "894",
              "decimalDigits": 2,
              "name": "Zambian kwacha",
              "active": false
            }
          ]
        }
      }

Rate calculation meta data

Any endpoint which returns rates (latest, historical, timeSeries, fluctuation) can optionally return rate calculation meta data. This data allows to understand where a rate comes from and how it was computed.

To query rate meta data, add the meta query field and any desired sub fields in the GraphQL query. Example for historical rates: 

  
    
      query HistoricalWithMeta {
        historical(date: "2020-05-15", baseCurrency: "PLN", quoteCurrencies: ["AMD"]) {
          baseCurrency
          quoteCurrency
          quote
          date
          meta {
            sourceShortNames
            sourceNames
            sourceIds
            sources {
              id
              shortName
              name
            }
            rateType
            calculated
            calculationShortDescription
            calculationDescription
            calculation {
              pathRate
              weight
              sourceRates {
                sourceId
                date
                baseCurrency
                quoteCurrency
                quote
                flipped
                fetched
                source {
                  id
                  shortName
                  name
                }
              }
            }
          }
        }
      }

Response: Rates with calculation meta data. 

  
    

            {
        "data" : {
          "historical" : [
            {
              "baseCurrency": "PLN",
              "quoteCurrency": "AMD",
              "quote": 115.392379,
              "date": "2020-05-15",
              "meta": {
                "sourceShortNames": "CBR",
                "sourceNames": "Central Bank of Russia",
                "sourceIds": ["cbr"],
                "sources": [
                  {
                    "id": "cbr",
                    "shortName": "CBR",
                    "name": "Central Bank of Russia"
                  }
                ],
                "rateType": "calculated",
                "calculated": true,
                "calculationShortDescription": "Calculated: 115.392379 from CBR (PLN/RUB, RUB/AMD)",
                "calculationDescription": "Calculated rate: 115.392379 from CBR (PLN/RUB 17.493600 with RUB/AMD 6.596263)",
                "calculation": [
                  {
                    "pathRate": 115.3923786782,
                    "weight": 1.0,
                    "sourceRates": [
                      {
                        "sourceId": "cbr",
                        "date": "2020-05-15",
                        "baseCurrency": "PLN",
                        "quoteCurrency": "RUB",
                        "quote": 17.4936,
                        "flipped": false,
                        "fetched": "2020-05-17T11:11:11Z",
                        "source": {
                          "id": "cbr",
                          "shortName": "CBR",
                          "name": "Central Bank of Russia"
                        }
                      },
                      {
                        "sourceId": "cbr",
                        "date": "2020-05-15",
                        "baseCurrency": "RUB",
                        "quoteCurrency": "AMD",
                        "quote": 6.5962625576,
                        "flipped": true,
                        "fetched": "2020-05-17T11:11:11Z",
                        "source": {
                          "id": "cbr",
                          "shortName": "CBR",
                          "name": "Central Bank of Russia"
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      }

arrow-up icon