{% extends 'dashboard/base.html' %} {% block title %}API Documentation - Peza{% endblock %} {% block breadcrumb %}API Documentation{% endblock %} {% block content %}

API Documentation

Base URL: {{ base_url }}

Quick Start Snippets

import requests
import time

api_key = "YOUR_API_KEY"
url = "https://developers.pezamw.com/api/locations/"
headers = {"X-API-Key": api_key}
params = {"location": "Lilongwe", "category": "hospital", "radius": 5000}
transient = {429, 500, 502, 503, 504}

for attempt in range(1, 5):
    response = requests.get(url, headers=headers, params=params, timeout=25)
    if response.status_code not in transient:
        break
    if attempt < 4:
        time.sleep(2 * attempt)

print(response.json())
const url = "https://developers.pezamw.com/api/locations/";
const apiKey = "YOUR_API_KEY";
const params = new URLSearchParams({
  location: "Lilongwe",
  category: "hospital",
  radius: "5000",
});

fetch(`${url}?${params}`, {
  method: "GET",
  headers: { "X-API-Key": apiKey },
})
  .then((res) => res.json())
  .then((data) => console.log(data))
  .catch((err) => console.error(err));
curl -G "https://developers.pezamw.com/api/locations/" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "location=Lilongwe" \
  --data-urlencode "category=hospital" \
  --data-urlencode "radius=5000"
<?php
$url = "https://developers.pezamw.com/api/locations/";
$params = http_build_query([
  "location" => "Lilongwe",
  "category" => "hospital",
  "radius" => 5000,
]);

$ch = curl_init($url . "?" . $params);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY"],
  CURLOPT_TIMEOUT => 25,
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

OCR API (Quick Example)

curl -X POST "https://api.pezamw.com/v1/ocr/text" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@invoice.jpg"

Local Data Enrichment API

Resolve Malawi districts, traditional authorities, villages, postal-like areas, and phone carriers.

Endpoints
  • GET /api/local/districts/?q= List districts
  • GET /api/local/traditional-authorities/?district=LLW List T/As by district
  • GET /api/local/villages/?ta=10101 List villages by T/A
  • GET /api/local/postal-areas/?q=Area&type=township Postal-like area lookup
  • GET /api/local/lookup/?district=Lilongwe&ta=Kalumbu Hierarchy lookup
  • POST /api/local/phone/validate/ Phone validation + carrier
  • POST /api/local/bulk/search/ Bulk lookup for map UIs
curl -X POST "https://developers.pezamw.com/api/local/phone/validate/" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\"phone\": \"+265 99 123 4567\"}'
{% for ep in api_endpoints %}

{{ ep.name }}

{{ ep.method }} — {{ ep.endpoint }}

{{ ep.description }}

{% if ep.auth %}
Auth: {{ ep.auth }}
{% endif %}

Code Snippet (curl)

{% if 'POST' in ep.method %}curl -X POST "{{ base_url }}{{ ep.endpoint }}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"example": true}'{% else %}curl -H "X-API-Key: YOUR_API_KEY" "{{ base_url }}{{ ep.endpoint }}"{% endif %}
{% if ep.parameters %}

Parameters

{% for p in ep.parameters %} {% endfor %}
NameTypeRequiredDescription
{{ p.name }} {{ p.type }} {% if p.required %}Yes{% else %}No{% endif %} {% if p.desc %} {{ p.desc }} {% elif p.description %} {{ p.description }} {% else %} - {% endif %}
{% endif %}

Example (curl)

{% if ep.name == 'Find Locations' %}curl -H "X-API-Key: your_key" "{{ base_url }}{{ ep.endpoint }}?location=Lilongwe&category=hospital"{% elif ep.name == 'Validate API Key' %}curl -X POST -H "Content-Type: application/json" -d '{"key":"YOUR_KEY"}' "{{ base_url }}{{ ep.endpoint }}"{% elif 'POST' in ep.method %}curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{}' "{{ base_url }}{{ ep.endpoint }}"{% else %}curl -H "X-API-Key: YOUR_API_KEY" "{{ base_url }}{{ ep.endpoint }}"{% endif %}

Response (example)

{% if ep.name == 'Find Locations' %}{
  "success": true,
  "count": 2,
  "locations": [
    {"name": "Lilongwe Central Hospital", "category": "hospital", "distance": "0.5 km"},
    {"name": "Area Police Station", "category": "police", "distance": "1.2 km"}
  ]
}{% elif ep.name == 'Validate API Key' %}{
  "valid": true,
  "quota_exceeded": false,
  "plan": "basic",
  "limit": 1000,
  "remaining": 987
}{% else %}{
  "success": true,
  "request_id": "uuid",
  "data": {}
}
{% endif %}
{% if ep.examples %}

More examples

    {% for ex_k, ex_v in ep.examples.items %}
  • {{ ex_k }}: {{ ex_v }}
    • {% endfor %}
{% endif %}
{% endfor %}
Authentication: Send your API key in the X-API-Key header or as api_key form/query parameter.
{% endblock %}