Overview

MediLoca is a healthcare location intelligence API that enables applications to discover nearby medical facilities, measure healthcare accessibility, retrieve emergency routing, locate specialist services, and evaluate community health risk — all using Maiaddy's Loccode as the primary location identifier.

Every request is built around a loccode — a unique identifier from the Maiaddy platform that pinpoints a specific geographic area at postcode-level precision. Send a loccode, and the API returns data for that exact location: nearby facilities, access scores, emergency routes, specialist recommendations, or community health risk.

The six endpoints

EndpointMethodPathWhat it returns

Get FacilitiesGET/mediloca/api/v1/facilitiesNearby healthcare facilities ranked by relevance, with travel time, insurance compatibility, and emergency support.

Get Healthcare AccessGET/mediloca/api/v1/accessAccess score, facility density, healthcare coverage, and gap detection.

Get Emergency RouteGET/mediloca/api/v1/emergency-routeNearest emergency facilities, routing estimates, navigation links, and emergency contacts.

Get Specialist RecommendationGET/mediloca/api/v1/specialistSpecialist matching by condition or symptom, with ranked hospital recommendations.

Get Health RiskGET/mediloca/api/v1/health-riskCommunity health risk score, environmental indicators, and disease prevalence data.

Get Health HeatmapGET/mediloca/api/v1/heatmapGeographic health visualisation.

NOTE

All intelligence endpoints use HTTP GET with query parameters. Include Authorization: Bearer YOUR_API_KEY on every request.

The Loccode

Every endpoint requires a loccode. Understanding how to use it correctly will save you from the most common errors.

What is a loccode?

A loccode is a structured alphanumeric code that maps to a specific postcode-level area in Nigeria. It is generated and validated by the Maiaddy location intelligence platform, which links GPS-confirmed coordinates to a unique code for that location.

Think of it like a postcode, except it maps to a real, GPS-confirmed area rather than a general postal district. Each loccode resolves to a specific state, LGA, and set of coordinates.

Sample Loccodes to Get You Started:

LA10E 2AC
LA15A 2JU

Loccodes are case-insensitive

The following values resolve to the same location:

LA10E 2AC
la10e 2ac
La10e 2ac

MediLoca normalises Loccodes automatically. However, documentation should still present them in uppercase.

The Loccode must be exact

A loccode must be submitted exactly as it was issued, with correct characters and correct spacing. The API does not correct or guess. Any mistake will cause the request to fail.

400 Bad Request: The loccode query parameter is missing from the request.
404 Not Found: A loccode was submitted but is malformed or not registered in the database.

IMPORTANT

If you are unsure of the exact format for a Loccode, retrieve it from the Maiaddy app. Do not guess or construct one manually.

The Loccode echoed back in a response may look slightly different from what you sent; for example KD10A 4SE may return as KD10A-4SE. This is only a display difference in the response output. It does not mean the API accepts both formats as input.

Authentication & Requests

API key

An API key is required for every request. Include it in the authorisation header:

Authorization: Bearer YOUR_API_KEY

Create an API Key here.

WARNING

Never put your API key in client-side code or any publicly visible location (including GitHub). Always call the Mediloca API from your server. Store your key in an environment variable; never hardcode it.

Request format

Every request to the Mediloca API must include the following headers.

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Intelligence endpoints pass parameters as query strings on the URL. Parameter names and string values are case-sensitive unless otherwise stated.

Response format

A successful request returns HTTP 200 OK with a JSON body. The response always echoes back the loccode that was sent. If something goes wrong, the API returns a non-200 status code with an error body. See Error reference for cross-endpoint HTTP semantics. Per-route error tables are under Get Facilities errors, Healthcare Access errors, Emergency Route errors, Specialist Recommendation errors, Health Risk errors, and Health Heatmap errors.

Endpoints

Get Facilities by Loccode

Returns healthcare facilities near a location. Results can be filtered by radius, facility level, and result limit. Each facility record includes accreditations, specialties, supported insurance plans, emergency availability, a relevance ranking score, and travel estimates.

GET

https://api.maiaddy.com/mediloca/api/v1/facilities?loccode=LA10E 2AC&radius_km=5&facility_level=Secondary&limit=2

Headers

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Query — Request parameters

FieldTypeRequiredDescription

loccodestringYesPatient or search origin Loccode. Must be exactly as issued. Example: LA10E 2AC

radius_kmnumberNoSearch radius in kilometres. Example: 10.0

facility_levelstringYesFilter by care level: Primary, Secondary, or Tertiary. Example: Secondary

limitintegerNoMaximum number of ranked facilities to return. Example: 5

Example query params

loccode=LA10E 2AC&radius_km=5&facility_level=Secondary&limit=2

Full curl command

curl -X GET \
  "https://api.maiaddy.com/mediloca/api/v1/facilities?loccode=LA10E%202AC&radius_km=5&facility_level=Secondary&limit=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "success": true,
  "message": "Facility search completed successfully",
  "timestamp": 1779786535292,
  "data": {
    "loccode": "LA10e 2ac",
    "location": {
      "lat": 6.6604933,
      "lon": 3.3214708,
      "state": "Lagos",
      "lga": "Ifako_Ijaye"
    },
    "filters": { "facility_level": "Secondary" },
    "count": 2,
    "radius_km": 5.0,
    "scoring": "Score = 0.35×distance + 0.25×travel_time + 0.20×accreditation + 0.10×capacity + 0.05×satisfaction + 0.05×wait",
    "generated_at": "2026-05-26T09:08:55Z",
    "facilities": [
      {
        "rank": 1,
        "name": "Ayodele Medical Center",
        "category": "Primary Health Center",
        "ownership": "Private",
        "state": "Lagos",
        "lga": "Ifako/Ijaye",
        "ward": "Tabon Tabon",
        "address": "Ayodele Medical Center, Tabon Tabon, Ifako/Ijaye, Lagos, Nigeria",
        "nhfr_code": "24/10/1/2/2/0007",
        "facility_level": "Secondary",
        "functional_status": "Functional",
        "accreditations": [{ "body": "NHFR", "status": "active" }, { "body": "MDCN", "status": "active" }],
        "specialties": ["Primary Care", "Immunisation", "Antenatal"],
        "distance_km": 0.47,
        "travel_time_minutes": 2.0,
        "emergency_services": true,
        "accepts_insurance_plans": ["Hygeia HMO", "AXA Mansard Health", "Reliance HMO", "Total Health Trust"],
        "beds_capacity": null,
        "wait_time_estimate_minutes": null,
        "ranking_score": 0.8137,
        "score_breakdown": {
          "distance_weight": 0.35,
          "travel_time_weight": 0.25,
          "accreditation_weight": 0.20,
          "capacity_weight": 0.10,
          "satisfaction_weight": 0.05,
          "wait_time_weight": 0.05
        }
      },
      {
        "rank": 2,
        "name": "Ifako Ijaiye General Hospital",
        "category": "General Hospital",
        "ownership": "Public",
        "state": "Lagos",
        "lga": "Ifako/Ijaye",
        "ward": "Ifako Coker",
        "address": "Ifako Ijaiye General Hospital, Ifako Coker, Ifako/Ijaye, Lagos, Nigeria",
        "nhfr_code": "24/10/1/2/1/0001",
        "facility_level": "Secondary",
        "functional_status": "Functional",
        "accreditations": [{ "body": "NHFR", "status": "active" }, { "body": "MDCN", "status": "active" }, { "body": "NHIA", "status": "active" }],
        "specialties": ["General Medicine", "Surgery", "Paediatrics", "Obstetrics", "Emergency"],
        "distance_km": 1.95,
        "travel_time_minutes": 6.0,
        "emergency_services": true,
        "accepts_insurance_plans": ["NHIS", "NSITF", "Hygeia HMO", "AXA Mansard Health", "Reliance HMO"],
        "beds_capacity": null,
        "wait_time_estimate_minutes": null,
        "ranking_score": 0.7503,
        "score_breakdown": {
          "distance_weight": 0.35,
          "travel_time_weight": 0.25,
          "accreditation_weight": 0.20,
          "capacity_weight": 0.10,
          "satisfaction_weight": 0.05,
          "wait_time_weight": 0.05
        }
      }
    ]
  }
}

Response fields

FieldTypeDescription

loccodestringLoccode echoed from the request.

locationobjectResolved coordinates and administrative labels (lat, lon, state, lga).

radius_kmnumberSearch radius applied.

filtersobjectActive filters such as facility_level.

countintegerNumber of facilities returned.

facilitiesarrayRanked facilities with distance_km, travel_time_minutes, accreditations, insurance plans, specialties, and ranking_score.

facilities[].ranking_scorenumberComposite score used for ordering (higher is better).

facilities[].score_breakdownobjectWeights applied for distance, travel time, accreditation, capacity, and wait time.

Errors

HTTP statusError codeWhat it meansWhat to do

400LOCCODE_REQUIREDThe loccode query parameter is missing from the request.Add the loccode query parameter. See The Loccode.

401UNAUTHORIZEDAPI key is missing or invalid.Include a valid Bearer token.

404LOCCODE_NOT_FOUNDThe Loccode is formatted incorrectly or does not match any registered location.Check the loccode. Retrieve the exact format from the Maiaddy app.

500INTERNAL_SERVER_ERRORAn unexpected server error occurred.Retry the request. If it continues, contact Mediloca support with the timestamp.

Get Healthcare Access

Returns a comprehensive measure of healthcare accessibility for a location. Use this endpoint to score facility availability, detect coverage gaps, identify the nearest care options by category, and support planning decisions for HMOs, NGOs, and government agencies.

GET

https://api.maiaddy.com/mediloca/api/v1/access?loccode=LA10E 2AC

Headers

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Query — Request parameters

FieldTypeRequiredDescription

loccodestringYesLoccode for the region to score. Example: LA10E 2AC

Example query params

loccode=LA10E 2AC

Full curl command

curl -X GET \
  "https://api.maiaddy.com/mediloca/api/v1/access?loccode=LA10E%202AC" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "loccode": "LA10E 2AC",
  "location": {
    "lat": 6.6604933,
    "lon": 3.3214708,
    "state": "Lagos",
    "lga": "Ifako_Ijaye"
  },
  "access_score": 87.4,
  "coverage_band": "Excellent",
  "score_breakdown": {
    "facility_density_5km": 30.0,
    "hospital_proximity": 24.4,
    "primary_care_proximity": 18.1,
    "emergency_proximity": 14.8,
    "nhia_coverage_rate": 0.1
  },
  "facility_counts": {
    "within_5km": 99,
    "within_10km": 238,
    "functional_within_10km": 130,
    "nhia_accredited_within_10km": 2
  },
  "nearest_by_type": {
    "primary_care": {
      "name": "Ayodele Medical Center",
      "category": "Primary Health Center",
      "distance_km": 0.47,
      "functional_status": "Functional"
    },
    "secondary_care": {
      "name": "Ayodele Medical Center",
      "category": "Primary Health Center",
      "distance_km": 0.47,
      "functional_status": "Functional"
    },
    "tertiary_care": {
      "name": "Sekafem Specialist Hospital",
      "category": "Specialist Hospital",
      "distance_km": 5.7,
      "functional_status": "Functional"
    },
    "emergency": {
      "name": "Sekafem Specialist Hospital",
      "category": "Specialist Hospital",
      "distance_km": 5.7,
      "functional_status": "Functional"
    },
    "maternity": {
      "name": "Obanto Maternity and Child Welfare Clinic",
      "category": "Maternity Home",
      "distance_km": 1.44,
      "functional_status": "Functional"
    }
  },
  "coverage_gaps": [
    { "specialty": "emergency", "gap_severity": "moderate", "nearest_km": 5.7 },
    { "specialty": "paediatrics", "gap_severity": "moderate", "nearest_km": 5.7 },
    { "specialty": "surgery", "gap_severity": "moderate", "nearest_km": 5.7 }
  ],
  "nhia_accreditation_rate_10km": 0.008,
  "interpretation": "≥4 functional facilities within 5km, hospital within 5km, NHIA coverage >75%",
  "use_cases": [
    "NHIA: Verify patient has accredited facility before enrollment approval",
    "NGOs: Identify and prioritize healthcare deserts for outreach",
    "HMOs: Show members their in-network access score before purchase",
    "Government: Data-driven planning for new facility placement"
  ],
  "generated_at": "2026-05-26T09:12:18Z"
}

Response fields

FieldTypeDescription

loccodestringLoccode queried.

locationobjectResolved lat, lon, state, and lga.

access_scorenumberRegional healthcare access score from 0 to 100.

coverage_bandstringSummary access band. Values: Poor, Adequate, Strong, Excellent.

score_breakdownobjectContributions from density, hospital proximity, primary care, emergency, and NHIA coverage.

facility_countsobjectCounts within 5 km and 10 km, including functional and NHIA-accredited facilities.

nearest_by_typeobjectNearest primary, secondary, tertiary, emergency, and maternity facilities.

coverage_gapsarrayIdentified gaps in coverage for outreach or planning.

interpretationstringPlain-language summary of access.

use_casesarray of stringsSuggested applications for NHIA, NGOs, HMOs, and government.

Errors

HTTP statusError codeWhat it meansWhat to do

400LOCCODE_REQUIREDThe loccode query parameter is missing from the request.Add the loccode query parameter. See The Loccode.

401UNAUTHORIZEDAPI key is missing or invalid.Include a valid Bearer token.

404LOCCODE_NOT_FOUNDThe Loccode is formatted incorrectly or does not match any registered location.Check the loccode. Retrieve the exact format from the Maiaddy app.

500INTERNAL_SERVER_ERRORAn unexpected server error occurred.Retry the request. If it continues, contact Mediloca support with the timestamp.

Get Emergency Route

Returns emergency routing recommendations for a location. The response identifies the nearest emergency-capable facilities, provides travel estimates, navigation links, and a list of Nigerian emergency contact numbers.

GET

https://api.maiaddy.com/mediloca/api/v1/emergency-route?loccode=LA15A 2JU

Headers

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Query — Request parameters

FieldTypeRequiredDescription

loccodestringYesThe Loccode for the emergency origin point. Example: LA15A 2JU

Example query params

loccode=LA15A 2JU

Full curl command

curl -X GET \
  "https://api.maiaddy.com/mediloca/api/v1/emergency-route?loccode=LA15A%202JU" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "success": true,
  "message": "Emergency route recommendation retrieved successfully",
  "timestamp": 1779786892961,
  "data": {
    "loccode": "LA15A 2JU",
    "location": {
      "lat": 6.5282223,
      "lon": 3.3708662,
      "state": "Lagos",
      "lga": "Mainland"
    },
    "nearest_emergency_facilities": [
      {
        "name": "Adams Maternity and Clinic Home",
        "category": "Maternity Home",
        "latitude": 6.6700744,
        "longitude": 3.3519884,
        "phone": null,
        "facility_level": "Secondary",
        "distance_km": 21.04,
        "travel_time_minutes": 22.0,
        "functional_status": "Functional",
        "google_maps_url": "https://www.google.com/maps/dir/6.5282223,3.3708662/6.6700744,3.3519884"
      },
      {
        "name": "Total Health Hospital",
        "category": "Primary Health Center",
        "latitude": 6.671325683,
        "longitude": 3.359924316,
        "phone": null,
        "facility_level": "Secondary",
        "distance_km": 21.64,
        "travel_time_minutes": 22.0,
        "functional_status": "Unknown",
        "google_maps_url": "https://www.google.com/maps/dir/6.5282223,3.3708662/6.671325683,3.359924316"
      },
      {
        "name": "God's Hope Hospital",
        "category": "Maternity Home",
        "latitude": 6.729425,
        "longitude": 3.405345,
        "phone": null,
        "facility_level": "Secondary",
        "distance_km": 27.7,
        "travel_time_minutes": 24.0,
        "functional_status": "Functional",
        "google_maps_url": "https://www.google.com/maps/dir/6.5282223,3.3708662/6.729425,3.405345"
      }
    ],
    "emergency_contacts": {
      "police": "112",
      "ambulance": "112",
      "fire": "112",
      "nema": "0800 033 3601"
    },
    "generated_at": "2026-05-26T09:14:52Z"
  }
}

Response fields

FieldTypeDescription

loccodestringThe Loccode queried, echoed back as submitted.

locationobjectResolved coordinates and administrative area for the Loccode.

nearest_emergency_facilitiesarrayRanked list of the closest emergency-capable facilities, each with distance, travel time, and a direct Google Maps navigation link.

emergency_contactsobjectNigerian emergency service numbers.

generated_atstringISO 8601 timestamp of when the response was generated.

Errors

HTTP statusError codeWhat it meansWhat to do

400LOCCODE_REQUIREDThe loccode query parameter is missing from the request.Add the loccode query parameter. See The Loccode.

401UNAUTHORIZEDAPI key is missing or invalid.Include a valid Bearer token.

404LOCCODE_NOT_FOUNDThe Loccode is formatted incorrectly or does not match any registered location.Check the loccode. Retrieve the exact format from the Maiaddy app.

500INTERNAL_SERVER_ERRORAn unexpected server error occurred.Retry the request. If it continues, contact Mediloca support with the timestamp.

Get Specialist Recommendation

Maps a health condition or symptom description to a predicted medical specialty, then returns a ranked list of facilities that offer that specialist care near the queried location.

GET

https://api.maiaddy.com/mediloca/api/v1/specialist?loccode=LA15A 2JU&health_condition=broken bone

Headers

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Query — Request parameters

FieldTypeRequiredDescription

loccodestringYesPatient Loccode. Example: LA15A 2JU

health_conditionstringYesThe condition or symptom to match to a specialist. Plain language is accepted. Example: broken bone

Example query params

loccode=LA15A 2JU&health_condition=broken bone

Full curl command

curl -X GET \
  "https://api.maiaddy.com/mediloca/api/v1/specialist?loccode=LA15A%202JU&health_condition=broken%20bone" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "success": true,
  "message": "Specialist recommendations retrieved successfully",
  "timestamp": 1779787005213,
  "data": {
    "loccode": "LA15A 2JU",
    "location": {
      "lat": 6.5282223,
      "lon": 3.3708662,
      "state": "Lagos",
      "lga": "Mainland"
    },
    "input_condition": "broken bone",
    "predicted_specialties": [{ "name": "Orthopedics", "confidence": 0.98 }],
    "recommended_specialists": [
      {
        "name": "Rabonni Specialist Hospital",
        "status": "Functional",
        "category": "Specialist Hospital",
        "coordinates": { "lat": 6.544785, "lon": 3.374063333 },
        "specialty_matched": "Orthopedics",
        "confidence_score": 0.98,
        "distance_km": 1.88,
        "facility_level": "Tertiary",
        "final_rank_score": 0.845
      },
      {
        "name": "German Friendship Specialist Hospital",
        "status": "Functional",
        "category": "Specialist Hospital",
        "coordinates": { "lat": 6.49784, "lon": 3.362503333 },
        "specialty_matched": "Orthopedics",
        "confidence_score": 0.98,
        "distance_km": 3.5,
        "facility_level": "Tertiary",
        "final_rank_score": 0.804
      },
      {
        "name": "Faari Specialist Hospital",
        "status": "Functional",
        "category": "Specialist Hospital",
        "coordinates": { "lat": 6.494, "lon": 3.37971 },
        "specialty_matched": "Orthopedics",
        "confidence_score": 0.98,
        "distance_km": 3.93,
        "facility_level": "Tertiary",
        "final_rank_score": 0.794
      }
    ]
  }
}

Response fields

FieldTypeDescription

loccodestringLoccode echoed from the request.

input_conditionstringCondition text as interpreted by the ML layer.

locationobjectResolved lat, lon, state, and lga.

predicted_specialtiesarraySpecialties inferred from the condition with confidence scores.

recommended_specialistsarrayProximity-ranked facilities with specialty_matched, confidence_score, distance_km, and final_rank_score.

Errors

HTTP statusError codeWhat it meansWhat to do

400LOCCODE_REQUIREDThe loccode query parameter is missing from the request.Add the loccode query parameter. See The Loccode.

401UNAUTHORIZEDAPI key is missing or invalid.Include a valid Bearer token.

404LOCCODE_NOT_FOUNDThe Loccode is formatted incorrectly or does not match any registered location.Check the loccode. Retrieve the exact format from the Maiaddy app.

500INTERNAL_SERVER_ERRORAn unexpected server error occurred.Retry the request. If it continues, contact Mediloca support with the timestamp.

Get Health Risk

Returns a community health risk assessment for a location. The response includes an overall risk index, environmental condition indicators, infrastructure quality data, and disease prevalence trends for the population in that area.

GET

https://api.maiaddy.com/mediloca/api/v1/health-risk?loccode=LA15A 2JU

Headers

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Query — Request parameters

FieldTypeRequiredDescription

loccodestringYesThe Loccode for the target location. Must be exactly as issued. Example: LA15A 2JU

Example query params

loccode=LA15A 2JU

Full curl command

curl -X GET \
  "https://api.maiaddy.com/mediloca/api/v1/health-risk?loccode=LA15A%202JU" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "success": true,
  "message": "Health risk analysis retrieved successfully",
  "timestamp": 1779787104065,
  "data": {
    "loccode": "LA15A 2JU",
    "location": {
      "lat": 6.5282223,
      "lon": 3.3708662,
      "state": "Lagos",
      "lga": "Mainland"
    },
    "health_risk_index": 36.4,
    "risk_level": "Moderate",
    "computation_breakdown": {
      "urban_density_stress_35pct": 28.0,
      "infrastructure_deficit_35pct": 0.0,
      "socio_economic_vulnerability_30pct": 8.4
    },
    "environmental_vitals": {
      "population_density_per_sqkm": 20000.0,
      "infrastructure_quality_score": 1.0,
      "crime_index": 3.5,
      "avg_income_index": 0.7,
      "nearby_facilities_10km": 42254
    },
    "disease_prevalence": {
      "malaria": { "source": "WHO Africa 2024", "trend": "stable", "prevalence_per_1000": 280.0 },
      "hypertension": { "source": "Nigeria NBS 2023", "trend": "increasing", "prevalence_per_1000": 180.0 },
      "diabetes_mellitus": { "source": "WHO 2024", "trend": "increasing", "prevalence_per_1000": 65.0 },
      "respiratory_infections": { "source": "NHMIS 2023", "trend": "stable", "prevalence_per_1000": 320.0 },
      "diarrheal_diseases": { "source": "UNICEF 2024", "trend": "decreasing", "prevalence_per_1000": 240.0 },
      "musculoskeletal_conditions": { "source": "WHO 2024", "trend": "stable", "prevalence_per_1000": 120.0 }
    }
  }
}

Response fields

FieldTypeDescription

loccodestringLoccode queried.

locationobjectResolved lat, lon, state, and lga.

health_risk_indexnumberComposite risk index for the Loccode area.

risk_levelstringBand such as Moderate or High.

computation_breakdownobjectWeighted contributions from urban density, infrastructure, and socio-economic factors.

environmental_vitalsobjectPopulation density, infrastructure score, crime index, income, and nearby facility counts.

disease_prevalenceobjectPer-disease prevalence per 1000 with source and trend.

Errors

HTTP statusError codeWhat it meansWhat to do

400LOCCODE_REQUIREDThe loccode query parameter is missing from the request.Add the loccode query parameter. See The Loccode.

401UNAUTHORIZEDAPI key is missing or invalid.Include a valid Bearer token.

404LOCCODE_NOT_FOUNDThe Loccode is formatted incorrectly or does not match any registered location.Check the loccode. Retrieve the exact format from the Maiaddy app.

500INTERNAL_SERVER_ERRORAn unexpected server error occurred.Retry the request. If it continues, contact Mediloca support with the timestamp.

Get Health Heatmap

Returns a geographic health visualisation for a location. Use this endpoint to retrieve heatmap points for facility strength and regional risk signals around a loccode.

GET

https://api.maiaddy.com/mediloca/api/v1/heatmap?loccode=LA13A 1ML

Headers

HeaderRequiredValue

AuthorizationYesBearer YOUR_API_KEY

Query — Request parameters

FieldTypeRequiredDescription

loccodestringYesCenter Loccode for the heatmap. Example: LA13A 1ML

Example query params

loccode=LA13A 1ML

Full curl command

curl -X GET \
  "https://api.maiaddy.com/mediloca/api/v1/heatmap?loccode=LA13A%201ML" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "loccode": "LA13A 1ML",
  "center": {
    "lat": 6.5885785,
    "lon": 3.3492144
  },
  "radius_km": 10.0,
  "heatmap_points": [
    {
      "lat": 6.65424,
      "lon": 3.27292,
      "type": "facility_strength",
      "intensity": 0.05,
      "label": "Femtake Convalescent Center"
    },
    {
      "lat": 6.59376632,
      "lon": 3.268632832,
      "type": "facility_strength",
      "intensity": 0.05,
      "label": "Baruwa Alimosho Primary Health Center"
    }
  ],
  "summary": {
    "facility_count": 999,
    "risk_nodes": 100
  }
}

Response fields

FieldTypeDescription

loccodestringLoccode queried.

centerobjectCenter point lat and lon.

radius_kmnumberRadius of the heatmap in kilometres.

heatmap_pointsarrayGeospatial nodes with lat, lon, type (facility_strength or risk), intensity, and label.

summaryobjectAggregate facility_count and risk_nodes for the area.

Errors

HTTP statusError codeWhat it meansWhat to do

400LOCCODE_REQUIREDThe loccode query parameter is missing from the request.Add the loccode query parameter. See The Loccode.

401UNAUTHORIZEDAPI key is missing or invalid.Include a valid Bearer token.

404LOCCODE_NOT_FOUNDThe Loccode is formatted incorrectly or does not match any registered location.Check the loccode. Retrieve the exact format from the Maiaddy app.

500INTERNAL_SERVER_ERRORAn unexpected server error occurred.Retry the request. If it continues, contact Mediloca support with the timestamp.

Error reference

HTTP error patterns the Mediloca API can return across any endpoint. Missing or invalid API keys typically produce 401 Unauthorized with the same JSON error envelope.

HTTP status codes — all endpoints

HTTP statusError codeWhat it meansWhat to do

400Bad RequestThe request is malformed — a required field is missing, a Loccode is incorrectly formatted, or a field value is not recognised.Check the query parameters. Make sure all required fields are present and the Loccode is exactly as issued (see The Loccode section).

401UnauthorizedThe API key is missing or invalid.Include a valid bearer token in the Authorisation header.

404Not FoundThe endpoint URL is wrong, or a Loccode does not match any registered location in the database.Verify the URL is correct and the Loccode exists in the Maiaddy platform.

429Too Many RequestsThe request rate limit has been exceeded. Default: 60 requests per minute per API key.Reduce request frequency. Use exponential backoff when retrying programmatically.

500Internal Server ErrorAn unexpected error occurred on the server.Retry after a short delay. Contact Mediloca support if it persists — include the request details and timestamp.

503Service UnavailableThe API or a data source it depends on is temporarily offline.Wait and retry. Contact support if the issue continues.

Error response examples

When an error occurs, the API returns a JSON body alongside the error status code:

{
  "error": {
    "code": "ERROR_CODE_STRING",
    "message": "A plain-language description of what went wrong.",
    "details": "Optional: additional context, such as which field failed."
  }
}

Quick reference

Endpoints at a glance

Required query parameters for each GET route — use with the overview table above when wiring clients or tests.

EndpointMethodPathRequired parameters

Get FacilitiesGET/mediloca/api/v1/facilitiesloccode, facility_level

Get Healthcare AccessGET/mediloca/api/v1/accessloccode

Get Emergency RouteGET/mediloca/api/v1/emergency-routeloccode

Get Specialist RecommendationGET/mediloca/api/v1/specialistloccode, health_condition

Get Health RiskGET/mediloca/api/v1/health-riskloccode

Get Health HeatmapGET/mediloca/api/v1/heatmaploccode

NOTE

All endpoints use HTTP GET with Authorization: Bearer YOUR_API_KEY.

Facility level values

Accepted values for the facility_level filter on Get Facilities:

Primary       Secondary       Tertiary

Get Healthcare Access returns a coverage_band such as:

Poor       Adequate       Strong       Excellent

Further Resources

Everything you need to go further with the Mediloca API.

SDKs

Official Python and Java SDKs for Mediloca are published to PyPI and Maven Central. See the Mediloca SDK guide for installation, authentication, and working examples for every endpoint.

The Loccode

Loccodes are generated and validated by the Maiaddy location intelligence platform. Retrieve them from the Maiaddy app — do not guess or construct one manually.

Getting help

For bug reports, feature requests, or integration questions, contact the Maiaddy team directly.

Email: developer@maiaddy.com
Web: maiaddy.com