Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pharmachains.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
POST /medicines/search

Returns a ranked list of verified pharmacies that have the specified medicine in stock within the given radius of the patient’s location. Results are sorted by proximity by default.

​
Request

const response = await fetch(
  "https://api.pharmachains.ai/v1/medicines/search",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
    },
    body: JSON.stringify({
      query: "Metformin 500mg",
      location: { lat: 6.5244, lng: 3.3792 },
      radius_km: 10,
      limit: 10
    })
  }
);

const { data } = await response.json();
console.log(data.results);

​
Body parameters

ParameterTypeRequiredDescription
querystringYesMedicine name, generic or brand. Minimum 2 characters.
locationobjectYesPatient’s lat and lng coordinates.
radius_kmintegerNoSearch radius in kilometres. Default: 10. Max: 50.
limitintegerNoMax number of results to return. Default: 10. Max: 50.

​
Response

​
200 — Success

{
  "success": true,
  "data": {
    "query": "Metformin 500mg",
    "total": 2,
    "results": [
      {
        "pharmacy_id": "ph_01J...",
        "name": "HealthPlus Pharmacy, Lekki",
        "address": "14 Admiralty Way, Lekki Phase 1, Lagos",
        "in_stock": true,
        "price_ngn": 2400,
        "distance_km": 1.2,
        "estimated_delivery_minutes": 35
      },
      {
        "pharmacy_id": "ph_02K...",
        "name": "MedPlus Pharmacy, VI",
        "address": "23 Adeola Odeku Street, Victoria Island, Lagos",
        "in_stock": true,
        "price_ngn": 2550,
        "distance_km": 3.1,
        "estimated_delivery_minutes": 55
      }
    ]
  }
}

​
Response fields

FieldTypeDescription
pharmacy_idstringUnique pharmacy identifier. Use this when creating a request.
namestringPharmacy display name and branch location.
addressstringFull street address of the pharmacy.
in_stockbooleanWhether the medicine is currently available.
price_ngnintegerPrice in Nigerian Naira.
distance_kmfloatDistance from the provided patient location.
estimated_delivery_minutesintegerEstimated time from order to patient delivery.

​
400 — Bad request

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The 'query' field is required.",
    "status": 400
  }
}

​
404 — No results

{
  "success": false,
  "error": {
    "code": "medicine_not_found",
    "message": "No pharmacies found for the specified query and location.",
    "status": 404
  }
}
Save the pharmacy_id from your preferred result and pass it directly to POST /requests to kick off fulfilment.