API Documentation | Bezal | Courier Rates API & Platform

Overview

The Bezal API provides real-time shipping rates and delivery estimates from multiple courier services. Calculate shipping costs between any two locations with weight-based pricing.

Base URL: https://shipping.romaxdesigns.co.ke/api/v1/

Route API requests require authentication via API key. See the Authentication section for details.

Authentication

Route API requests require an API key for authentication. Include the key in your requests using one of the methods below.

Bearer Token Authorization: Bearer {api_key}

Recommended method using Bearer token in Authorization header.

Example Header

Authorization: Bearer sk_live_1234567890abcdef

/route Endpoint

GET /route

Get shipping rates for a specific route and weight.

Parameters

Parameter	Type	Required	Description
`origin` Required	string	Yes	Origin city or location
`destination` Required	string	Yes	Destination city or location
`weight` Required	float	Yes	Package weight in kilograms (Kg) (0.1-100)

Example Request

cURL Example

curl -X GET "https://shipping.romaxdesigns.co.ke/api/v1/route?origin=Nairobi&destination=Thika&weight=8.5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Test This Endpoint

Code Examples

Node.js Example (Do not expose your API key in browser code.)


const API_KEY = "YOUR_API_KEY";

async function getShippingRates(origin, destination, weight) {

    const params = new URLSearchParams({
        origin: origin,
        destination: destination,
        weight: weight
    });

    const response = await fetch(
        `https://shipping.romaxdesigns.co.ke/api/v1/route?${params}`,
        {
            method: "GET",
            headers: {
                "Authorization": `Bearer ${API_KEY}`
            }
        }
    );

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

    return await response.json();
}


// Usage
getShippingRates("Nairobi", "Thika", 8.5)
    .then(data => {
        console.log("Shipping Rates:");
        const formatted = JSON.stringify(data, null, 2);
    })
    .catch(error => {
        console.error("Error:", error);
    });

PHP Example

<?php
function getShippingRates($origin, $destination, $weight) {
    $api_key = 'YOUR_API_KEY';
    // Build query string
    $params = http_build_query([
        'origin' => $origin,
        'destination' => $destination,
        'weight' => $weight
    ]);
    $url = 'https://shipping.romaxdesigns.co.ke/api/v1/route?' . $params;
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $api_key
    ]);
    $response = curl_exec($ch);
    if (curl_errno($ch)) {
        return [
            'error' => curl_error($ch)
        ];
    }
    curl_close($ch);
    return json_decode($response, true);
}

// Usage: Get shipping rates for Nairobi to Thika route when weight is 8.5 kg
$rates = getShippingRates('Nairobi', 'Thika', 8.5);

?>

Python Example

import requests

API_KEY = "YOUR_API_KEY"

def get_shipping_rates(origin, destination, weight):
    url = f"https://shipping.romaxdesigns.co.ke/api/v1/route"

    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }

    params = {
        "origin": origin,
        "destination": destination,
        "weight": weight
    }

    try:
        response = requests.get(
            url,
            headers=headers,
            params=params
        )

        response.raise_for_status()
        return response.json()

    except requests.exceptions.RequestException as e:
        return {
            "error": str(e)
        }


# Usage
rates = get_shipping_rates("Nairobi", "Thika", 8.5)

Java Example

import okhttp3.*;
import java.io.IOException;

public class ShippingClient {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://shipping.romaxdesigns.co.ke/api/v1/route").newBuilder();
        urlBuilder.addQueryParameter("origin", "Nairobi");
        urlBuilder.addQueryParameter("destination", "Mombasa");
        urlBuilder.addQueryParameter("weight", "5");

        Request request = new Request.Builder()
            .url(urlBuilder.build())
            .get()
            .addHeader("Authorization", "Bearer YOUR_API_KEY")
            .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
            System.out.println(response.body().string());
        }
    }
}

Error Codes

HTTP Status	Code	Description
200	SUCCESS	Request successful
400	VALIDATION_ERROR	Invalid parameters
401	INVALID_API_KEY	Authentication failed.
401	MISSING_API_KEY	API key is required
401	INVALID_API_KEY	Missing or invalid API key
429	RATE_LIMIT_EXCEEDED	Too many requests
429	NO_CREDIT_BALANCE	Your API credit balance has been exhausted
500	INTERNAL_ERROR	Server error

Error Response Format

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Weight must be greater than 0",
  "code": 400
}

Bezal API