Currency Rates API

Production-ready currency rates collector and historical JSON API.

Repository: https://github.com/Webisso/currency-api/

Features

• Free and fast static JSON responses
• No rate limiting on published static endpoints
• Daily data collection and build pipeline
• Versioned API by date (latest and YYYY-MM-DD)
• Pretty and minified JSON formats
• Local REST/static server for development
• Fallback-ready client utility for CDN failover

API URL Structure

GitHub Pages:

https://webisso.github.io/currency-api/{date}/{apiVersion}/{endpoint}

jsDelivr (GitHub repository distribution):

https://cdn.jsdelivr.net/gh/Webisso/currency-api@main/docs/{date}/{apiVersion}/{endpoint}

Format rules:

• date: latest or YYYY-MM-DD
• apiVersion: v1
• endpoint formats:
  • /{endpoint}.json
  • /{endpoint}.min.json

Endpoints

/currencies

• Returns all supported currencies list.
• Example: /latest/v1/currencies.json
• Minified: /latest/v1/currencies.min.json

/currencies/{base}

• Returns full conversion table using {base} as base currency.
• Example: /latest/v1/currencies/eur.json
• Date example: /2026-05-25/v1/currencies/eur.json
• Minified: /latest/v1/currencies/eur.min.json

/convert/?from=USD&to=EUR&unit=10

• Latest conversion with query parameters.
• Returns structured JSON view with source, target, TRY rates, rate and converted amount.
• Pages example: https://webisso.github.io/currency-api/latest/v1/convert/?from=USD&to=EUR&unit=10
• jsDelivr example: https://cdn.jsdelivr.net/gh/Webisso/currency-api@main/docs/latest/v1/convert/?from=USD&to=EUR&unit=10

/convert.js

• Browser module for programmatic conversion.
• Pages: https://webisso.github.io/currency-api/latest/v1/convert.js
• jsDelivr: https://cdn.jsdelivr.net/gh/Webisso/currency-api@main/docs/latest/v1/convert.js

Live-Style Examples

• https://webisso.github.io/currency-api/latest/v1/currencies.json
• https://webisso.github.io/currency-api/latest/v1/currencies/usd.json
• https://webisso.github.io/currency-api/2026-05-25/v1/currencies/eur.min.json

jsDelivr equivalents:

• https://cdn.jsdelivr.net/gh/Webisso/currency-api@main/docs/latest/v1/currencies.json
• https://cdn.jsdelivr.net/gh/Webisso/currency-api@main/docs/latest/v1/currencies/usd.json
• https://cdn.jsdelivr.net/gh/Webisso/currency-api@main/docs/2026-05-25/v1/currencies/eur.min.json

Fallback Pattern

Recommended client strategy:

1. Try jsDelivr URL first.
2. If it fails, fallback to GitHub Pages URL.

You can use the built-in helper at src/client/fetchCurrencyApi.js.

Local Usage

npm install
npm run fetch
npm run build:api
npm start

Local examples:

• http://localhost:3000/health
• http://localhost:3000/latest/v1/currencies.json
• http://localhost:3000/latest/v1/currencies/eur.json
• http://localhost:3000/2026-05-25/v1/currencies/usd.min.json

Project Structure

.github/
  workflows/
    daily-fetch.yml
src/
  fetchRates.js
  buildApi.js
  saveFile.js
  server.js
  client/
    fetchCurrencyApi.js
  utils/
    date.js
    xmlValidator.js
    ratesXmlParser.js
data/
  YYYY/
    MM/
      YYYY-MM-DD.xml
docs/
  latest/
  YYYY-MM-DD/

Snapshot dosya adlari calisma gunune gore degil, kaynak XML icindeki yayin tarihine gore yazilir. Kaynak saglayici ayni bulteni birden fazla gun sunarsa data/ ve docs/ yeni bir tarih klasoru uretmez.

CI/CD

• daily-fetch.yml
  • Scheduled fetch at 17:30 Turkey time (14:30 UTC)
  • Retries source fetch on transient failures
  • Builds JSON API outputs
  • Commits data/ and docs/ only when changes exist
  • Works with GitHub Pages source set to main /docs

Configuration

Environment variables:

• CURRENCY_SOURCE_URL (default: current XML source URL)

This keeps the system provider-agnostic so source feeds can be changed later without architecture changes.