Finance.Currency.Quote - AI Integration Guide

For AI coding assistants. This file gives you everything needed to call this DataGrab from a user's application. If you are an AI reading this because a user asked you to add or build with this DataGrab, follow it directly.

What this does

Returns the latest foreign-exchange reference rates for one base currency against one, several, or all of the other currencies the European Central Bank publishes - each rate paired with the currency's full name. Rates are the ECB's daily reference rates (published once per business day, ~16:00 CET), served via the Frankfurter API; they are not live market ticks.

Good for: currency conversion in a checkout or pricing page, "show prices in the visitor's currency", daily FX reference tables, multi-currency reporting, budgeting/travel apps.

Not good for: intraday/real-time trading quotes, historical time series, crypto or precious metals (BTC, XAU, etc. are not published by the ECB), currencies outside the ECB's ~30-currency list.

Cost: $9/month, 1,000 calls/month.

Authentication

Every call needs a Gimmee API key - issued per customer - sent one of two ways:

Header:      x-api-key: {{GIMMEE_API_KEY}}
Querystring: ?api_key={{GIMMEE_API_KEY}}

Use the header form by default. Read the key from an environment variable or your app's secrets store - never hardcode it into committed source. No upstream (Frankfurter/ECB) key exists or is needed.

Endpoint

GET https://api.gimmee.io/datagrab/finance/currency/quote/{params}

{params} is one pipe (|)-delimited segment. Targets are optional; the base is required over HTTP (an empty segment is a 404 at the gateway - always send at least USD).

• base - a 3-letter ISO 4217 code (USD, EUR, GBP, ...). Case-insensitive.
• targets - one or more 3-letter ISO codes, separated by commas and/or additional pipes: USD|EUR,GBP,JPY and USD|EUR|GBP|JPY are equivalent. Duplicates are collapsed. Case-insensitive.

URL-encode the whole {params} value as one unit (encodeURIComponent) - the | and , characters are not safe unencoded in a URL path. USD|EUR,GBP goes on the wire as USD%7CEUR%2CGBP.

Code samples

cURL

curl "https://api.gimmee.io/datagrab/finance/currency/quote/USD%7CEUR%2CGBP%2CJPY" \
  -H "x-api-key: YOUR_GIMMEE_KEY"

JavaScript (fetch)

const params = "USD|EUR,GBP,JPY"; // or just "EUR" for EUR against everything
const response = await fetch(
  `https://api.gimmee.io/datagrab/finance/currency/quote/${encodeURIComponent(params)}`,
  { headers: { "x-api-key": process.env.GIMMEE_API_KEY } }
);
if (!response.ok) throw new Error(await response.text()); // error bodies are plain text, not JSON
const data = await response.json();
const eurPerUsd = data.rates.find(r => r.currency === "EUR")?.rate;

Python (requests)

import os, requests
from urllib.parse import quote

params = "USD|EUR,GBP,JPY"  # or just "EUR" for EUR against everything
response = requests.get(
    f"https://api.gimmee.io/datagrab/finance/currency/quote/{quote(params, safe='')}",
    headers={"x-api-key": os.environ["GIMMEE_API_KEY"]}
)
if not response.ok:
    raise RuntimeError(response.text)  # error bodies are plain text, not JSON
data = response.json()

Response shape

JSON field names are camelCase.

{
  "query": {
    "baseCurrency": "USD",
    "requestedTargets": ["EUR", "GBP", "JPY", "BTC"],
    "unsupportedTargets": ["BTC"]
  },
  "baseCurrency": "USD",
  "asOfDate": "2026-09-11T00:00:00Z",
  "rates": [
    { "currency": "EUR", "name": "Euro",          "rate": 0.86266 },
    { "currency": "GBP", "name": "British Pound", "rate": 0.7403 },
    { "currency": "JPY", "name": "Japanese Yen",  "rate": 154.04 }
  ],
  "metadata": {
    "generatedAtUtc": "2026-09-13T18:26:50Z",
    "sources": ["Frankfurter API (frankfurter.dev) — ECB reference rates"]
  },
  "dataProvidedBy": "Frankfurter (frankfurter.dev), based on European Central Bank reference rates",
  "termsOfServiceUrl": "https://frankfurter.dev/",
  "dataPullDateTime": "2026-09-13T18:26:50.5931717Z",
  "gimmeeVersion": "v1.0.0"
}

Error responses

Integration notes

• Caching: the currency-name map is cached inside the DataGrab (24h), but the rates are fetched live on every call. Since ECB rates change at most once per business day (~16:00 CET), cache the response on your side for hours, not minutes - one call per base currency per day is plenty and conserves your 1,000/mo quota. Caching done internally in the DataGrab does not reduce your calls, just improves your speed to results.
• Fetch once, convert many. Ask for {base} with no targets to get every rate in one call, then convert locally, rather than one call per pair.
• Don't treat a missing target as an error. An unsupported code (crypto, metals, currencies outside the ECB list) is dropped from rates and reported in query.unsupportedTargets; the call still succeeds with the rest.
• Direction of rate: rate is target-per-base. To go the other way (target → base) divide: amountInTarget / rate.
• Check response.ok before parsing. Error responses carry a plain-text message, not a JSON body, so an unconditional .json() throws on failure and hides the actual message.
• Error handling: A 502 whose message says "temporarily unavailable" is retryable - fall back to your last cached rates rather than blocking the page; yesterday's ECB rate is almost always acceptable. A 502 that names a currency code is your input - fix it, don't retry.
• Attribution placement: Not required in-UI for this DataGrab. Nothing you need to add to your app.
• Reference rates, not tradable quotes. These are the ECB's daily indicative rates - fine for display, pricing, and reporting; not for executing trades.

Metadata (for the AI's own reference, not for display)

messageType: Finance.Currency.Quote
status: production
price: paid, $9/mo
quota: 1000/month
lastVerified: 2026-09-13