> ## 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.

# Search medicines

> Find a medicine and get a ranked list of pharmacies that have it in stock

## 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

<CodeGroup>
  ```javascript fetch theme={null}
  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);
  ```

  ```javascript axios theme={null}
  import axios from "axios";

  const { data } = await axios.post(
    "https://api.pharmachains.ai/v1/medicines/search",
    {
      query: "Metformin 500mg",
      location: { lat: 6.5244, lng: 3.3792 },
      radius_km: 10,
      limit: 10
    },
    {
      headers: {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log(data.results);
  ```
</CodeGroup>

### Body parameters

| Parameter   | Type    | Required | Description                                                |
| ----------- | ------- | -------- | ---------------------------------------------------------- |
| `query`     | string  | Yes      | Medicine name, generic or brand. Minimum 2 characters.     |
| `location`  | object  | Yes      | Patient's `lat` and `lng` coordinates.                     |
| `radius_km` | integer | No       | Search radius in kilometres. Default: `10`. Max: `50`.     |
| `limit`     | integer | No       | Max number of results to return. Default: `10`. Max: `50`. |

## Response

### 200 — Success

```json theme={null}
{
  "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

| Field                        | Type    | Description                                                   |
| ---------------------------- | ------- | ------------------------------------------------------------- |
| `pharmacy_id`                | string  | Unique pharmacy identifier. Use this when creating a request. |
| `name`                       | string  | Pharmacy display name and branch location.                    |
| `address`                    | string  | Full street address of the pharmacy.                          |
| `in_stock`                   | boolean | Whether the medicine is currently available.                  |
| `price_ngn`                  | integer | Price in Nigerian Naira.                                      |
| `distance_km`                | float   | Distance from the provided patient location.                  |
| `estimated_delivery_minutes` | integer | Estimated time from order to patient delivery.                |

### 400 — Bad request

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

### 404 — No results

```json theme={null}
{
  "success": false,
  "error": {
    "code": "medicine_not_found",
    "message": "No pharmacies found for the specified query and location.",
    "status": 404
  }
}
```

<Tip>
  Save the `pharmacy_id` from your preferred result and pass it directly to [POST /requests](/api-reference/endpoint/create) to kick off fulfilment.
</Tip>