Developer documentation

MPA Public API

Programmatic access to real-time emergency bed availability across Accra. Designed for ambulance dispatch systems, government integrations, and third-party health applications.

Auth

X-API-Key header

Rate limit

100 req/min (default)

Access

Read-only

Overview

All public endpoints are read-only and live under a single base URL. Responses are JSON; timestamps are ISO-8601 UTC.

Base URL

text

https://<your-backend-host>/api/v1/external

Authentication

Every request must include your API key in the X-API-Key header. Keys are issued by the platform admin and tied to a specific organization and contact email.

Need a key?

Email support@mpa.gh with your organization name and intended use case. Keys are usually issued within one business day.

bash

curl -H "X-API-Key: sk_live_..." "https://<your-backend-host>/api/v1/external/categories"

Rate limits

Each key has a per-minute request budget, configurable by the platform admin. The default is 100 requests/minute. Exceeding your limit returns 429 Too Many Requests — back off and retry after the window resets.

If you expect sustained traffic (e.g. an ambulance dispatch system polling continuously), request a higher limit when you apply for a key.

List hospitals

Retrieve a paginated list of hospitals on the platform. Optionally filter by bed category, or provide caller coordinates to receive each hospital's distance in kilometres.

GEThttps://<your-backend-host>/api/v1/external/hospitals

Parameters

Name	In	Type	Description
`category_id`	query	string (UUID)	Filter to hospitals that offer this bed category.
`latitude`	query	number	Caller latitude. If provided together with longitude, each result includes distance_km.
`longitude`	query	number	Caller longitude. Paired with latitude.
`page`	query	integer	Page number, starting at 1. Default: `1`
`per_page`	query	integer (1–100)	Results per page. Default: `20`

Example request

bash

curl -H "X-API-Key: $ACCRABEDS_API_KEY" \
  "https://<your-backend-host>/api/v1/external/hospitals?latitude=5.6037&longitude=-0.1870&per_page=20"

Example response

json

{
  "data": [
    {
      "id": "8f1b…",
      "name": "Korle Bu Teaching Hospital",
      "address": "Guggisberg Ave, Accra",
      "latitude": 5.5358,
      "longitude": -0.2275,
      "phone": "+233302739581",
      "distance_km": 7.8,
      "available_beds": { "general": 12, "icu": 2 },
      "total_available": 14
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 24 }
}

Search hospitals by radius

Find hospitals within a radius of a caller's coordinates. Useful for ambulance dispatch — pass the patient's lat/lng and get back nearby facilities sorted by distance or by available beds.

GEThttps://<your-backend-host>/api/v1/external/hospitals/search

Parameters

Name	In	Type	Description
`latitude`required	query	number (-90 to 90)	Caller latitude.
`longitude`required	query	number (-180 to 180)	Caller longitude.
`category_ids`	query	array of string	Repeat the param to filter to specific bed categories (e.g. category_ids=...&category_ids=...).
`sort_by`	query	"distance" \| "availability"	Sort order for the results. Default: `distance`
`radius_km`	query	number (1–500)	Search radius in kilometres. Default: `50`
`page`	query	integer	Page number. Default: `1`
`per_page`	query	integer (1–100)	Results per page. Default: `20`

Example request

bash

curl -H "X-API-Key: $ACCRABEDS_API_KEY" \
  "https://<your-backend-host>/api/v1/external/hospitals/search?latitude=5.6037&longitude=-0.1870&radius_km=15&sort_by=availability"

Example response

Same shape as List hospitals. distance_km is always populated because lat/lng are required.

json

{
  "data": [
    {
      "id": "8f1b…",
      "name": "37 Military Hospital",
      "address": "Liberation Rd, Accra",
      "latitude": 5.5855,
      "longitude": -0.1866,
      "phone": "+233302776111",
      "distance_km": 2.1,
      "available_beds": { "general": 8, "trauma": 3 },
      "total_available": 11
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 3 }
}

Hospital detail

Retrieve detailed information for a single hospital, including a ready-to-open directions URL and the full per-category bed breakdown.

GEThttps://<your-backend-host>/api/v1/external/hospitals/{hospital_id}

Parameters

Name	In	Type	Description
`hospital_id`required	path	string (UUID)	The hospital's unique identifier.

Example request

bash

curl -H "X-API-Key: $ACCRABEDS_API_KEY" \
  "https://<your-backend-host>/api/v1/external/hospitals/8f1b8c4e-2d7c-4f5d-9b11-aab1122cc33d"

Example response

json

{
  "data": {
    "id": "8f1b…",
    "name": "Korle Bu Teaching Hospital",
    "address": "Guggisberg Ave, Accra",
    "latitude": 5.5358,
    "longitude": -0.2275,
    "phone": "+233302739581",
    "distance_km": null,
    "directions_url": "https://www.google.com/maps/dir/?api=1&destination=5.5358,-0.2275",
    "bed_details": [
      { "category_id": "…", "category_name": "General", "available_count": 12, "total_capacity": 40 }
    ]
  }
}

Hospital availability

Real-time per-category bed availability for a single hospital. Cheaper than the detail endpoint if you only need bed counts. Every row includes last_updated_at so you can display staleness.

GEThttps://<your-backend-host>/api/v1/external/hospitals/{hospital_id}/availability

Parameters

Name	In	Type	Description
`hospital_id`required	path	string (UUID)	The hospital's unique identifier.

Example request

bash

curl -H "X-API-Key: $ACCRABEDS_API_KEY" \
  "https://<your-backend-host>/api/v1/external/hospitals/8f1b8c4e-2d7c-4f5d-9b11-aab1122cc33d/availability"

Example response

json

{
  "data": [
    {
      "category_id": "c1…",
      "category_name": "General Emergency Beds",
      "available_count": 12,
      "total_capacity": 40,
      "last_updated_at": "2026-04-20T11:42:00Z"
    }
  ]
}

List bed categories

Retrieve every bed category defined on the platform. Use these IDs with the category filters on the other endpoints.

GEThttps://<your-backend-host>/api/v1/external/categories

No parameters.

Example request

bash

curl -H "X-API-Key: $ACCRABEDS_API_KEY" \
  "https://<your-backend-host>/api/v1/external/categories"

Example response

json

{
  "data": [
    { "id": "c1…", "name": "General Emergency Beds" },
    { "id": "c2…", "name": "ICU / Critical Care Beds" }
  ]
}

Errors

Errors return a standard JSON envelope. The HTTP status code is the primary signal.

Status	Name	When you'll see it
`401`	Unauthorized	Missing or invalid X-API-Key header. Check the key value and that it is still active.
`403`	Forbidden	The key is valid but has been deactivated by the platform admin.
`422`	Unprocessable Entity	Request validation failed (e.g. coordinate out of range, category_id malformed).
`429`	Too Many Requests	Rate limit exceeded. Back off and retry after the window resets.

json

{
  "detail": [
    {
      "loc": ["query", "latitude"],
      "msg": "value is not a valid float",
      "type": "type_error.float"
    }
  ]
}