> ## Documentation Index
> Fetch the complete documentation index at: https://dos.dzaleka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Services API

> Retrieve information about services and organizations in Dzaleka Refugee Camp

## GET /api/services

Retrieve a list of all services and organizations available in Dzaleka Refugee Camp.

### Query Parameters

This endpoint does not require any query parameters.

### Response Format

<ResponseField name="status" type="string" required>
  Status of the API response ("success" or "error")
</ResponseField>

<ResponseField name="count" type="number" required>
  Total number of services returned
</ResponseField>

<ResponseField name="data" type="object" required>
  Container for the services data

  <ResponseField name="services" type="array" required>
    Array of service objects

    <ResponseField name="id" type="string">
      Unique identifier for the service
    </ResponseField>

    <ResponseField name="collection" type="string">
      Collection name ("services")
    </ResponseField>

    <ResponseField name="title" type="string">
      Name of the service or organization
    </ResponseField>

    <ResponseField name="category" type="string">
      Service category (e.g., "Education", "Legal Services", "Technology")
    </ResponseField>

    <ResponseField name="description" type="string">
      Detailed description of the service
    </ResponseField>

    <ResponseField name="location" type="object">
      Physical location information

      <ResponseField name="address" type="string">
        Street address
      </ResponseField>

      <ResponseField name="city" type="string">
        City name
      </ResponseField>

      <ResponseField name="coordinates" type="object">
        GPS coordinates

        <ResponseField name="lat" type="number">
          Latitude
        </ResponseField>

        <ResponseField name="lng" type="number">
          Longitude
        </ResponseField>
      </ResponseField>
    </ResponseField>

    <ResponseField name="contact" type="object">
      Contact information

      <ResponseField name="email" type="string">
        Email address
      </ResponseField>

      <ResponseField name="phone" type="string">
        Phone number
      </ResponseField>

      <ResponseField name="hours" type="string">
        Operating hours
      </ResponseField>
    </ResponseField>

    <ResponseField name="socialMedia" type="object">
      Social media links

      <ResponseField name="facebook" type="string">
        Facebook URL
      </ResponseField>

      <ResponseField name="twitter" type="string">
        Twitter/X URL
      </ResponseField>

      <ResponseField name="instagram" type="string">
        Instagram URL
      </ResponseField>

      <ResponseField name="linkedin" type="string">
        LinkedIn URL
      </ResponseField>

      <ResponseField name="website" type="string">
        Website URL
      </ResponseField>
    </ResponseField>

    <ResponseField name="logo" type="string">
      URL to organization logo
    </ResponseField>

    <ResponseField name="featured" type="boolean">
      Whether the service is featured
    </ResponseField>

    <ResponseField name="verified" type="boolean">
      Whether the service is verified
    </ResponseField>

    <ResponseField name="lastUpdated" type="string">
      Last update date (YYYY-MM-DD)
    </ResponseField>
  </ResponseField>
</ResponseField>

### Error Responses

<ResponseField name="status" type="string">
  "error"
</ResponseField>

<ResponseField name="message" type="string">
  Error message description
</ResponseField>

<ResponseField name="error" type="string">
  Detailed error information
</ResponseField>

**Status Codes:**

* `200` - Success
* `429` - Rate limit exceeded (60 requests per minute)
* `500` - Internal server error

### Rate Limiting

All API endpoints are rate-limited to 60 requests per minute per IP address. Rate limit headers are included in responses:

* `X-RateLimit-Limit`: Maximum requests per window
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Timestamp when the rate limit resets
* `Retry-After`: Seconds to wait before retrying (only on 429 responses)

### Example Request

```bash theme={null}
curl -X GET "https://services.dzaleka.com/api/services" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "count": 2,
  "data": {
    "services": [
      {
        "id": "BloomBox",
        "collection": "services",
        "title": "BloomBox Design Labs",
        "category": "Education",
        "description": "BloomBox Design Labs is dedicated to the application of sustainable design strategies, materials, and energy to advancing access to high quality education.",
        "location": {
          "address": "BloomBox, Dzaleka, M16",
          "city": "Dowa",
          "coordinates": {
            "lat": -13.6628274,
            "lng": 33.8704301
          }
        },
        "contact": {
          "email": "",
          "phone": "+1 236-888-5055",
          "hours": "Monday-Friday, 9:00 AM - 5:00 PM"
        },
        "socialMedia": {
          "facebook": "",
          "twitter": "https://x.com/roux_sofie",
          "instagram": "https://www.instagram.com/bloomboxdesignlabs/?hl=en",
          "linkedin": "",
          "website": "https://www.bloomboxdesignlabs.com/"
        },
        "logo": "https://static.wixstatic.com/media/bd2625_69e11c70797246ccba3425b1b8bcd771%7Emv2.png/v1/fill/w_192%2Ch_192%2Clg_1%2Cusm_0.66_1.00_0.01/bd2625_69e11c70797246ccba3425b1b8bcd771%7Emv2.png",
        "featured": true,
        "verified": true,
        "lastUpdated": "2025-03-06"
      }
    ]
  }
}
```

## POST /api/services

Retrieve services data with optional metadata and statistics.

### Request Body

<ParamField body="options" type="object">
  Optional configuration for the response

  <ParamField body="includeMetadata" type="boolean">
    Include export metadata in response
  </ParamField>

  <ParamField body="includeStats" type="boolean">
    Include statistics in response
  </ParamField>
</ParamField>

### Response Format

Same as GET endpoint, with optional additional fields:

<ResponseField name="metadata" type="object">
  Export metadata (only if `includeMetadata: true`)

  <ResponseField name="exportDate" type="string">
    ISO 8601 timestamp of export
  </ResponseField>

  <ResponseField name="collection" type="string">
    Collection name
  </ResponseField>
</ResponseField>

<ResponseField name="stats" type="object">
  Statistics (only if `includeStats: true`)

  <ResponseField name="totalItems" type="number">
    Total number of items
  </ResponseField>

  <ResponseField name="collection" type="string">
    Collection name
  </ResponseField>
</ResponseField>

### Example Request

```bash theme={null}
curl -X POST "https://services.dzaleka.com/api/services" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "includeMetadata": true,
      "includeStats": true
    }
  }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "count": 45,
  "data": {
    "services": [
      {
        "id": "BloomBox",
        "title": "BloomBox Design Labs",
        "category": "Education"
      }
    ]
  },
  "metadata": {
    "exportDate": "2025-03-09T12:00:00.000Z",
    "collection": "services"
  },
  "stats": {
    "totalItems": 45,
    "collection": "services"
  }
}
```

## Implementation

The Services API is implemented using the `createGetHandler` and `createPostHandler` utility functions from `src/utils/api-utils.ts:118`.

Source code: `src/pages/api/services.ts:5`