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 info@kursikembimit.al to request access.

Authentication

All API endpoints require authentication using an API key. Include your key in the X-API-Key header with every request.

⚠️ 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.

Limit	Window
60 requests	Per minute

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

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., `bkt`, `raiffeisen`)
`currency` optional	string	Filter by currency code (e.g., `EUR`, `USD`)

Example Request

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

Response 200 OK

{
    "success": true,
    "data": [
        {
            "bank": {
                "slug": "bkt",
                "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"

Response 200 OK

{
    "success": true,
    "data": {
        "currency": {
            "code": "EUR",
            "name": "Euro",
            "symbol": "€"
        },
        "date": "2025-12-24",
        "rates": [
            {
                "bank": {
                    "slug": "bkt",
                    "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": "bkt", ... },
            "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=bkt" \
     -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": "bkt", "buy": "98.3000", "sell": "98.8000" }
                ]
            },
            {
                "date": "2025-12-18",
                "rates": [
                    { "bank": "bkt", "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/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": "bkt",
            "name": "Banka Kombëtare Tregtare",
            "short_name": "BKT",
            "logo_url": "https://kursikembimit.al/images/provider/bkt.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., `bkt`, `raiffeisen`, `intesa-sanpaolo`)

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/bkt" \
     -H "X-API-Key: your_api_key"

Response 200 OK

{
    "success": true,
    "data": {
        "bank": {
            "slug": "bkt",
            "name": "Banka Kombëtare Tregtare",
            "short_name": "BKT",
            "logo_url": "https://kursikembimit.al/images/provider/bkt.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': 'bkt'}
).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
`bkt`	Banka Kombëtare Tregtare
`raiffeisen`	Raiffeisen Bank
`intesa-sanpaolo`	Intesa Sanpaolo Bank Albania
`credins`	Credins Bank
`otp`	OTP Bank Albania
`tirana-bank`	Tirana Bank
`first-investment-bank`	First Investment Bank Albania
`united-bank-of-albania`	United Bank of Albania
`american-bank-of-investments`	American Bank of Investments
`procredit`	ProCredit Bank Albania
`union-bank`	Union Bank
`infoeuro-ecb`	InfoEuro (ECB Reference Rates)

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

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