Skip to main content

​
Introduction

The Dzaleka Online Services API provides programmatic access to community data including services, events, news, jobs, resources, and more. The API is built on Astro and uses a RESTful architecture with JSON responses.
The API is currently public and free to use with rate limiting to ensure fair usage.

​
Base URL

All API requests should be made to: 
https://services.dzaleka.com/api

​
Available Endpoints

The API provides access to the following collections:

Services

Community services and organizations

Events

Upcoming and past community events

News

Latest news and announcements

Jobs

Job opportunities and listings

Resources

Educational and community resources

Photos

Community photo gallery

Profiles

Community member profiles

Talents

Showcase of community talents

Weather

Local weather forecast for Dowa district

Search

Search across all collections

​
API Architecture

​
Collection Endpoints

Most endpoints follow a standardized pattern using shared utility functions from src/utils/api-utils.ts:118-159:
  • GET requests fetch all items in a collection
  • POST requests fetch items with optional filters and metadata
  • OPTIONS requests handle CORS preflight

​
Standard Response Format

All successful API responses follow this structure: 
{
  "status": "success",
  "count": 25,
  "data": {
    "services": [
      {
        "id": "example-service",
        "collection": "services",
        "title": "Example Service",
        "description": "Service description",
        "category": "Healthcare",
        "...": "..."
      }
    ]
  }
}
The exact fields in each data object depend on the collection type. All items include id and collection fields.

​
Making Requests

​
GET Request Example

Fetch all services: 
curl https://services.dzaleka.com/api/services
Response: 
{
  "status": "success",
  "count": 15,
  "data": {
    "services": [
      {
        "id": "healthcare-center",
        "collection": "services",
        "title": "Dzaleka Health Center",
        "description": "Primary healthcare services",
        "category": "Healthcare"
      }
    ]
  }
}

​
POST Request Example

Fetch services with metadata: 
curl -X POST https://services.dzaleka.com/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "includeMetadata": true,
      "includeStats": true
    }
  }'
Response: 
{
  "status": "success",
  "count": 15,
  "data": {
    "services": [...]
  },
  "metadata": {
    "exportDate": "2026-03-09T10:30:00.000Z",
    "collection": "services"
  },
  "stats": {
    "totalItems": 15,
    "collection": "services"
  }
}

​
Search Request Example

Search across multiple collections: 
curl "https://services.dzaleka.com/api/search?q=education&collections=services,resources&limit=5"
Response: 
{
  "status": "success",
  "query": "education",
  "totalResults": 8,
  "results": {
    "services": [
      {
        "slug": "education-center",
        "title": "Community Education Center",
        "description": "Adult education programs",
        "collection": "services",
        "url": "/services/education-center"
      }
    ],
    "resources": [...]
  },
  "cached": false
}
Search results are cached for 5 minutes to improve performance. Check the cached field and X-Cache header.

​
Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

​
Error Response Format

{
  "status": "error",
  "message": "Descriptive error message",
  "error": "Technical error details"
}

​
Common HTTP Status Codes

​
200
Success
Request completed successfully
​
400
Bad Request
Invalid request parameters (e.g., search query too short)
​
429
Rate Limit Exceeded
Too many requests. See Rate Limits for details
​
500
Internal Server Error
Server error while processing the request

​
Error Handling Example

curl "https://services.dzaleka.com/api/search?q=a"
Response (400 Bad Request): 
{
  "status": "error",
  "message": "Search query must be at least 2 characters long"
}

​
Response Headers

All API responses include standard headers for CORS and caching: 
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
Some endpoints include additional headers:
  • X-Cache: HIT or MISS (for cached responses)
  • Cache-Control: Caching directives for client-side caching
  • X-RateLimit-*: Rate limit information (see Rate Limits)

​
Best Practices

Stay within the 60 requests per minute limit. Implement exponential backoff when receiving 429 responses.
Many endpoints include Cache-Control headers. Implement client-side caching to reduce API calls.
Always check the status field in responses and handle errors appropriately.
When you need metadata or statistics, use POST requests with the options parameter.
When using the search endpoint, specify only the collections you need to improve performance.

​
Next Steps

Authentication

Learn about CORS and required headers

Rate Limits

Understand rate limiting and how to handle it