API Documentation - Kursi Kembimit

Getting Started

Base URL

https://kursikembimit.al/api

Quick Start

To use the Kursi Kembimit API, you need an API key. Include it in all requests using the X-API-Key header.

curl -X GET "https://kursikembimit.al/api/rates" \
     -H "X-API-Key: your_api_key_here"

📧 Need an API key? Contact us at [email protected] to request access.

Authentication

Every endpoint below requires an API key in the X-API-Key header. A key gives you your own hourly quota and usage statistics; ask for one through the contact page.

⚠️ Important: Keep your API key secret. Do not expose it in client-side code or public repositories.

Request Header

Header	Value	Description
`X-API-Key`	`your_api_key`	Your unique API key

Authentication Error Response

{
    "error": "API key required",
    "message": "Please provide an API key in the X-API-Key header."
}

Rate Limiting

API requests are rate limited to ensure fair usage and service stability.

Per	Limit
IP address and API key	60 requests per minute per IP address, and the key's own hourly quota (1000 requests per hour unless agreed otherwise)

When you exceed a limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Rates change at most every 30 minutes. Responses carry an ETag and may be cached for 60 seconds; send If-None-Match to get a 304 when nothing changed.

API Endpoints

GET /api/rates

Get all exchange rates for today or a specific date. Returns rates from all banks.

Query Parameters

Parameter	Type	Description
`date` optional	string	Date in YYYY-MM-DD format. Defaults to today.
`bank` optional	string	Filter by bank slug (e.g., `banka-kombetare-tregtare`, `raiffeisen-bank-albania`)
`currency` optional	string	Filter by currency code (e.g., `EUR`, `USD`)

Example Request

curl -X GET "https://kursikembimit.al/api/rates?bank=banka-kombetare-tregtare¤cy=EUR" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": [
        {
            "bank": {
                "slug": "banka-kombetare-tregtare",
                "name": "Banka Kombëtare Tregtare",
                "short_name": "BKT"
            },
            "currency": {
                "code": "EUR",
                "name": "Euro",
                "symbol": "€"
            },
            "buy_rate": "98.5000",
            "sell_rate": "99.0000",
            "rate_date": "2025-12-24",
            "updated_at": "2025-12-24T09:00:00+01:00"
        }
    ],
    "meta": {
        "date": "2025-12-24",
        "count": 1
    }
}

GET /api/rates/{currency}

Get exchange rates for a specific currency from all banks. Includes best buy/sell rates.

Path Parameters

Parameter	Type	Description
`currency` required	string	Currency code (e.g., `EUR`, `USD`, `GBP`)

Query Parameters

Parameter	Type	Description
`date` optional	string	Date in YYYY-MM-DD format. Defaults to today.

Example Request

curl -X GET "https://kursikembimit.al/api/rates/EUR" \
     -H "X-API-Key: your_api_key"

rates lists every published rate. best_buy and best_sell only consider exchange offers from active banks: the Bank of Albania reference rate and InfoEuro are listed but never chosen. spread is null when a bank publishes only one side.

Response 200 OK

{
    "success": true,
    "data": {
        "currency": {
            "code": "EUR",
            "name": "Euro",
            "symbol": "€"
        },
        "date": "2025-12-24",
        "rates": [
            {
                "bank": {
                    "slug": "banka-kombetare-tregtare",
                    "name": "Banka Kombëtare Tregtare",
                    "short_name": "BKT"
                },
                "buy_rate": "98.5000",
                "sell_rate": "99.0000",
                "spread": 0.5076
            }
        ],
        "best_buy": {
            "bank": { "slug": "raiffeisen", ... },
            "buy_rate": "98.7000"
        },
        "best_sell": {
            "bank": { "slug": "banka-kombetare-tregtare", ... },
            "sell_rate": "98.9000"
        }
    },
    "meta": {
        "count": 10
    }
}

GET /api/rates/{currency}/history

Get historical exchange rates for a specific currency. Useful for trend analysis and charts.

Path Parameters

Parameter	Type	Description
`currency` required	string	Currency code (e.g., `EUR`, `USD`)

Query Parameters

Parameter	Type	Description
`days` optional	integer	Number of days to look back. Default: 30, Max: 90
`bank` optional	string	Filter by bank slug

Example Request

curl -X GET "https://kursikembimit.al/api/rates/EUR/history?days=7&bank=banka-kombetare-tregtare" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": {
        "currency": {
            "code": "EUR",
            "name": "Euro"
        },
        "history": [
            {
                "date": "2025-12-17",
                "rates": [
                    { "bank": "banka-kombetare-tregtare", "buy": "98.3000", "sell": "98.8000" }
                ]
            },
            {
                "date": "2025-12-18",
                "rates": [
                    { "bank": "banka-kombetare-tregtare", "buy": "98.4000", "sell": "98.9000" }
                ]
            }
        ]
    },
    "meta": {
        "days": 7,
        "from": "2025-12-17",
        "to": "2025-12-24"
    }
}

GET /api/rates/currencies

Get a list of all available currencies in the system.

Example Request

curl -X GET "https://kursikembimit.al/api/rates/currencies" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": [
        { "code": "EUR", "name": "Euro", "symbol": "€", "is_active": true },
        { "code": "USD", "name": "US Dollar", "symbol": "$", "is_active": true },
        { "code": "GBP", "name": "British Pound", "symbol": "£", "is_active": true },
        { "code": "CHF", "name": "Swiss Franc", "symbol": "CHF", "is_active": true }
    ],
    "meta": {
        "count": 4
    }
}

GET /api/convert

Convert an amount between a foreign currency and the lek (ALL) at today's rates. Without bank, the best offer of the day is used: the highest buy rate when converting into lek, the lowest sell rate when converting out of it. The Bank of Albania reference rate and InfoEuro are never used as offers.

Query Parameters

Parameter	Type	Description
`from`	string	Currency code you have, e.g. `EUR` or `ALL`
`to`	string	Currency code you want; one side must be `ALL`
`amount`	number	Amount of `from` to convert
`bank` optional	string	Use this bank's rate (slug, see Available Banks)

Example Request

curl -X GET "https://kursikembimit.al/api/convert?from=EUR&to=ALL&amount=100" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": {
        "from": "EUR",
        "to": "ALL",
        "amount": 100,
        "result": 9091,
        "rate": 90.91,
        "bank": { "slug": "ak-invest", "name": "AK Invest" },
        "date": "2026-10-15"
    }
}

GET /api/banks

Get a list of all active banks providing exchange rates.

Example Request

curl -X GET "https://kursikembimit.al/api/banks" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": [
        {
            "slug": "banka-kombetare-tregtare",
            "name": "Banka Kombëtare Tregtare",
            "short_name": "BKT",
            "logo_url": "https://kursikembimit.al/images/provider/bkt-h100-k.png",
            "website": "https://www.bkt.com.al"
        },
        {
            "slug": "raiffeisen",
            "name": "Raiffeisen Bank",
            "short_name": "Raiffeisen",
            "logo_url": "https://kursikembimit.al/images/provider/raiffeisen.png",
            "website": "https://www.raiffeisen.al"
        }
    ],
    "meta": {
        "count": 10
    }
}

GET /api/banks/{slug}

Get detailed information about a specific bank, including current exchange rates.

Path Parameters

Parameter	Type	Description
`slug` required	string	Bank slug (e.g., `banka-kombetare-tregtare`, `raiffeisen-bank-albania`, `banka-credins`)

Query Parameters

Parameter	Type	Description
`date` optional	string	Date in YYYY-MM-DD format. Defaults to today.

Example Request

curl -X GET "https://kursikembimit.al/api/banks/banka-kombetare-tregtare" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": {
        "bank": {
            "slug": "banka-kombetare-tregtare",
            "name": "Banka Kombëtare Tregtare",
            "short_name": "BKT",
            "logo_url": "https://kursikembimit.al/images/provider/bkt-h100-k.png",
            "website": "https://www.bkt.com.al"
        },
        "date": "2025-12-24",
        "rates": [
            {
                "currency": { "code": "EUR", "name": "Euro", "symbol": "€" },
                "buy_rate": "98.5000",
                "sell_rate": "99.0000",
                "spread": 0.5076
            },
            {
                "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
                "buy_rate": "92.3000",
                "sell_rate": "93.0000",
                "spread": 0.7584
            }
        ]
    },
    "meta": {
        "rates_count": 4
    }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

HTTP Status Codes

Status Code	Description
200 OK	Request successful
401 Unauthorized	Missing or invalid API key
404 Not Found	Resource not found (invalid currency/bank)
429 Too Many Requests	Rate limit exceeded

Error Response Format

{
    "success": false,
    "error": "Currency not found",
    "message": "Currency with code 'XYZ' was not found."
}

Code Examples

JavaScript (Fetch)

const API_KEY = 'your_api_key';
const BASE_URL = 'https://kursikembimit.al/api';

async function getExchangeRates(currency = 'EUR') {
    const response = await fetch(`${BASE_URL}/rates/${currency}`, {
        headers: {
            'X-API-Key': API_KEY
        }
    });

    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data;
}

// Usage
getExchangeRates('EUR')
    .then(data => {
        console.log('Best buy rate:', data.data.best_buy);
        console.log('Best sell rate:', data.data.best_sell);
    })
    .catch(error => console.error('Error:', error));

Python (Requests)

import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://kursikembimit.al/api'

def get_exchange_rates(currency='EUR', date=None):
    headers = {'X-API-Key': API_KEY}
    params = {}

    if date:
        params['date'] = date

    response = requests.get(
        f'{BASE_URL}/rates/{currency}',
        headers=headers,
        params=params
    )
    response.raise_for_status()
    return response.json()

# Usage
data = get_exchange_rates('EUR')
print(f"Best buy rate: {data['data']['best_buy']}")
print(f"Best sell rate: {data['data']['best_sell']}")

# Get historical rates
history = requests.get(
    f'{BASE_URL}/rates/EUR/history',
    headers={'X-API-Key': API_KEY},
    params={'days': 30, 'bank': 'banka-kombetare-tregtare'}
).json()

for day in history['data']['history']:
    print(f"{day['date']}: {day['rates']}")

PHP (cURL)

<?php

$apiKey = 'your_api_key';
$baseUrl = 'https://kursikembimit.al/api';

function getExchangeRates($currency = 'EUR') {
    global $apiKey, $baseUrl;

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => "$baseUrl/rates/$currency",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "X-API-Key: $apiKey"
        ]
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("HTTP Error: $httpCode");
    }

    return json_decode($response, true);
}

// Usage
try {
    $data = getExchangeRates('EUR');
    echo "Best buy: " . $data['data']['best_buy']['buy_rate'] . "\n";
    echo "Best sell: " . $data['data']['best_sell']['sell_rate'] . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Available Banks

Use these slugs when filtering by bank:

Slug	Bank Name
`banka-e-shqiperise`	Banka e Shqipërisë (official reference rate)
`raiffeisen-bank-albania`	Raiffeisen Bank Albania
`banka-credins`	Banka Credins
`fibank-albania`	Fibank Albania
`otp-bank-albania`	OTP Bank Albania
`banka-kombetare-tregtare`	Banka Kombëtare Tregtare
`united-bank-of-albania`	United Bank of Albania
`ak-invest`	AK Invest
`iliria-98`	Iliria 98
`infoeuro-ecb`	InfoEuro (ECB reference rates, units per 1 EUR, not lek)

Supported Currencies

Code	Name	Symbol
`EUR`	Euro	€
`USD`	US Dollar	$
`GBP`	British Pound	£
`CHF`	Swiss Franc	CHF
`CAD`	Canadian Dollar	C$
`AUD`	Australian Dollar	A$
`ALL`	Albanian Lek	L

📊 Kursi Kembimit API

Getting Started

Base URL

Quick Start

Authentication

Request Header

Authentication Error Response

Rate Limiting

API Endpoints

Query Parameters

Example Request

Response 200 OK

Path Parameters

Query Parameters

Example Request

Response 200 OK

Path Parameters

Query Parameters

Example Request

Response 200 OK

Example Request

Response 200 OK

Query Parameters

Example Request

Response 200 OK

Example Request

Response 200 OK

Path Parameters

Query Parameters

Example Request

Response 200 OK

Error Handling

HTTP Status Codes

Error Response Format

Code Examples

JavaScript (Fetch)

Python (Requests)

PHP (cURL)

Available Banks

Supported Currencies