bank-al-maghrib-exchange-rate — Bank Al-Maghrib exchange rates for Node.js

Official Bank Al-Maghrib (Morocco) exchange rates in Node.js and TypeScript with the bank-al-maghrib-exchange-rate npm package: latest published table, any historical date, daily series. Zero dependencies, types included.

Bank Al-Maghrib · Morocco · home currency MAD · published every business day

Installation

npm install bank-al-maghrib-exchange-rate
# or
yarn add bank-al-maghrib-exchange-rate
pnpm add bank-al-maghrib-exchange-rate

The same code is also published under the org scope as @allratestoday/bank-al-maghrib-exchange-rate — identical versions, pick whichever naming fits your dependency policy. Zero runtime dependencies; ESM and CommonJS builds; TypeScript definitions included.

Quick start

You need a free API key from allratestoday.com/register — no credit card, and the latest Bank Al-Maghrib table is on every plan.

import { getRate } from 'bank-al-maghrib-exchange-rate';

const pair = await getRate('USD', 'MAD', { apiKey: 'art_live_...' });
console.log(pair.rate, pair.rate_date);
// the official Bank Al-Maghrib rate, on the central bank's own publication date

API reference

Four functions, all returning promises. Every function takes an options object with your apiKey; the package throws before making a request if it is missing.

getRate(source, target, options)

Free plan and up. One pair from the latest published table. Pairs Bank Al-Maghrib does not print directly are resolved from its own table and flagged (see published vs derived).

const pair = await getRate('USD', 'MAD', { apiKey: 'art_live_...' });

// →
{
  bank: 'bam',
  name: 'Bank Al-Maghrib',
  rate_date: '2026-08-21',   // Bank Al-Maghrib's own publication date
  source: 'USD',
  target: 'MAD',
  rate: 0.854774,
  rate_type: 'reference',
  derived: false,
  method: 'published',       // 'published' | 'inverse' | 'cross'
  disclaimer: '…'
}

getLatestRates(options)

Free plan and up. The complete table for the latest publication date — one call, every currency Bank Al-Maghrib prints.

import { getLatestRates } from 'bank-al-maghrib-exchange-rate';

const table = await getLatestRates({ apiKey: 'art_live_...' });
console.log(table.rate_date, table.rates.length);

// →
{
  bank: 'bam',
  name: 'Bank Al-Maghrib',
  rate_date: '2026-08-21',
  rates: [
    { base: 'MAD', quote: 'USD', type: 'reference', value: 1.1699 },
    // … the rest of the published table
  ],
  disclaimer: '…'
}

getRatesForDate(date, options)

Paid plans. The official table for any past date. Weekends and holidays return the most recent published table, flagged via published_on_requested_date — exactly the in-force rate a filing or invoice needs. Pass source/target in the options to narrow to one pair.

import { getRatesForDate } from 'bank-al-maghrib-exchange-rate';

const day = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...' });
const one = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...', source: 'USD', target: 'MAD' });

// →
{
  bank: 'bam',
  requested_date: '2026-06-30',
  rate_date: '2026-06-30',              // the date actually published
  published_on_requested_date: true,    // false when a weekend/holiday fell back
  rates: [ /* the full table for that date */ ],
  disclaimer: '…'
}

getHistory(query, options)

Paid plans. One resolved rate per publication date across a range — for charts, revaluation runs or audit workpapers. Pass { symbol: 'USD' } instead of source/target to get the raw published rows for one currency.

import { getHistory } from 'bank-al-maghrib-exchange-rate';

const series = await getHistory(
  { source: 'USD', target: 'MAD', from: '2026-01-01', to: '2026-08-21' },
  { apiKey: 'art_live_...' }
);

// →
{
  bank: 'bam',
  source: 'USD',
  target: 'MAD',
  from: '2026-01-01',
  to: '2026-08-21',
  count: 152,
  rates: [
    { date: '2026-08-21', rate: 0.854774, rate_type: 'reference', derived: false, method: 'published' },
    // … one entry per publication date
  ],
  disclaimer: '…'
}

Published vs derived rates

If Bank Al-Maghrib does not print a pair directly, the API resolves it from the central bank's own table and says so — official and computed values are never mixed:

Error handling

Errors are thrown as Error with status (HTTP code) and body (the API's JSON error) attached:

try {
  const pair = await getRate('USD', 'XXX', { apiKey: 'art_live_...' });
} catch (err) {
  console.log(err.message); // human-readable reason
  console.log(err.status);  // e.g. 404
}

TypeScript and CommonJS

Full definitions ship with the package — no @types install:

import type { LatestRates, PairRate, DatedRates, RateEntry, HistoryQuery, RequestOptions } from 'bank-al-maghrib-exchange-rate';

CommonJS works too:

const { getRate } = require('bank-al-maghrib-exchange-rate');

getRate('USD', 'MAD', { apiKey: 'art_live_...' }).then((pair) => console.log(pair.rate));

Quota tips

• Bank Al-Maghrib publishes every business day — cache the table locally and a small monthly quota goes a long way.
• Every request counts toward your AllRatesToday quota, shared across all endpoints on your key.
• Prefer getLatestRates (one call, whole table) over many getRate calls when you need several pairs.

Under the hood

The package is a thin, dependency-free wrapper over the REST endpoints documented on the Bank Al-Maghrib rates page:

GET /api/v1/central-bank/bam/latest?source=USD&target=MAD
GET /api/v1/central-bank/bam/latest
GET /api/v1/central-bank/bam/2026-06-30
GET /api/v1/central-bank/bam/history?source=USD&target=MAD&from=2026-01-01&to=2026-08-21

Same data is available as CSV/XLSX downloads on the no-code download page, and to AI agents via the MCP server.

FAQ

Related