API Documentation

Welcome to the Calenzy API documentation. This guide will help you integrate with our APIs to access currency data, exchange rates, and more.

Base URL: All API requests should be made to https://api.calenzy.app

Getting Started

To use the Calenzy API, you'll need an API key. You can obtain one by signing up at calenzy.app.

Sign up at calenzy.app to get your API key
Include your API key in the Authorization header
Make requests to the API endpoints
Handle responses and errors appropriately

Authentication

All API requests must include your API key in the Authorization header using the Bearer token format.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Keep your API key secure! Never share your API key in public repositories or client-side code.

Rate Limiting

The Calenzy API implements rate limiting to ensure fair usage. Each API key has a monthly quota.

Currencies API: 10,000 requests per month

Rate Limit Headers

Every API response includes headers with information about your current rate limit status:

Header	Description
`X-RateLimit-Limit`	The maximum number of requests allowed per month
`X-RateLimit-Remaining`	The number of requests remaining in the current month
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

Need higher limits? Contact us to discuss custom plans.

Error Handling

The Calenzy API uses conventional HTTP response codes to indicate the success or failure of requests. Errors include detailed messages in multiple languages.

Error Response Format

Error Response

{
  "status": "error",
  "error_code": "unauthorised_key",
  "error_message": {
    "en": "Incorrect API key.",
    "fr": "Clé API incorrecte.",
    "es": "Clave API incorrecta."
  }
}

HTTP Status Codes

Code	Error Code	Description
`200`	-	Success - Request completed successfully
`400`	`bad_request`	Bad Request - The request was malformed or missing required parameters
`401`	`unauthorised_key`	Unauthorized - Invalid or missing API key
`404`	`wrong_path`	Not Found - The requested endpoint doesn't exist
`404`	`no_data`	Not Found - No data found for your request
`405`	`unauthorised_method`	Method Not Allowed - HTTP method not supported for this endpoint
`429`	`quota_exceeded`	Too Many Requests - Monthly quota exceeded

Currencies API

The Currencies API provides access to comprehensive currency data including multilingual names, symbols, and real-time exchange rates.

GET /v1/currencies

Retrieve a list of all available currencies with names in multiple languages.

Response

Returns an array of currency objects with the following properties:

Field	Type	Description
`code`	string	ISO 4217 currency code (e.g., "USD", "EUR")
`en`	string	Currency name in English
`fr`	string	Currency name in French
`es`	string	Currency name in Spanish
`de`	string	Currency name in German
`zh`	string	Currency name in Chinese (Simplified)
`tw`	string	Currency name in Chinese (Traditional)
`kr`	string	Currency name in Korean
`jp`	string	Currency name in Japanese
`symbol`	string	Currency symbol (e.g., "$", "€")
`is_crypto`	integer	0 or 1 indicating if it's a cryptocurrency
`is_metal`	integer	0 or 1 indicating if it's a precious metal

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/currencies" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/currencies', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data);
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.calenzy.app/v1/currencies';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key
]);

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

if ($http_code == 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: " . $response;
}
?>

Example Response

200 OK

[
  {
    "code": "USD",
    "en": "United States Dollar",
    "fr": "Dollar américain",
    "es": "Dólar estadounidense",
    "de": "US-Dollar",
    "zh": "美元",
    "tw": "美元",
    "kr": "미국 달러",
    "jp": "米ドル",
    "symbol": "$",
    "is_crypto": 0,
    "is_metal": 0
  },
  {
    "code": "EUR",
    "en": "Euro",
    "fr": "Euro",
    "es": "Euro",
    "de": "Euro",
    "zh": "欧元",
    "tw": "歐元",
    "kr": "유로",
    "jp": "ユーロ",
    "symbol": "€",
    "is_crypto": 0,
    "is_metal": 0
  }
]

GET /v1/currencies/rates

Get the latest exchange rates for all currencies.

Response

Returns an array of exchange rate objects with the following properties:

Field	Type	Description
`code`	string	ISO 4217 currency code
`rate`	number	Exchange rate relative to the base currency

Exchange rates are updated regularly and reflect the latest market data.

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/currencies/rates" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/currencies/rates', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data);
  // Access rate limit headers
  console.log('Rate Limit:', response.headers.get('X-RateLimit-Limit'));
  console.log('Remaining:', response.headers.get('X-RateLimit-Remaining'));
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.calenzy.app/v1/currencies/rates';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key
]);

$response = curl_exec($ch);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
curl_close($ch);

// Parse rate limit headers
preg_match('/X-RateLimit-Remaining: (\d+)/', $header, $matches);
$remaining = $matches[1] ?? 'N/A';

$data = json_decode($body, true);
echo "Remaining requests: " . $remaining . "\n";
print_r($data);
?>

Example Response

200 OK

[
  {
    "code": "USD",
    "rate": 1.0
  },
  {
    "code": "EUR",
    "rate": 0.85
  },
  {
    "code": "GBP",
    "rate": 0.73
  },
  {
    "code": "JPY",
    "rate": 110.5
  },
  {
    "code": "CAD",
    "rate": 1.25
  }
]

Response Headers

Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1704067199
Content-Type: application/json; charset=utf-8

Need help? Visit calenzy.com or contact our support team.