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

# Make Your Mutasib Shop Discoverable with Public Search

> Use the Mutasib public API to search products across shops, list nearby shops, and browse a shop's public catalog with no authentication.

Mutasib includes a built-in public marketplace that lets customers discover shops and browse products without needing a Mutasib account. This page explains the public API endpoints and how to enable location-based discovery so nearby customers can find your shop.

<Note>
  Public search visibility is controlled from the [Mutasib dashboard](https://mutasib.com/dashboard). This guide focuses on the endpoints that read from the public marketplace.
</Note>

## Public search endpoints

All of the endpoints in this section are **unauthenticated** — no token required. They are intended for customer-facing surfaces such as storefronts, mobile apps, or embed widgets.

### Search across all shops

Use the main search endpoint to find products matching a query, optionally filtered by category, price range, or a specific shop.

```bash theme={null}
# Search for "milk" in the grocery category, priced between 0 and 50
curl "https://api.mutasib.com/api/v1/public/search/?q=milk&category=grocery&min_price=0&max_price=50"

# Search within a specific shop
curl "https://api.mutasib.com/api/v1/public/search/?q=bread&shop_id=42"
```

All query parameters are optional — omitting `q` returns all visible products (useful for browsing by category).

### List all visible shops

Filter shops by category using the optional `category` query parameter, or omit it to return every visible shop. The response is paginated.

```bash theme={null}
# All visible shops
curl https://api.mutasib.com/api/v1/public/shops/

# Shops in a specific category
curl "https://api.mutasib.com/api/v1/public/shops/?category=grocery"
```

### Get a single shop's details

```bash theme={null}
curl https://api.mutasib.com/api/v1/public/shops/42/
```

### List a shop's public products

Use `search` to match against product names and `category_id` to filter by category — both parameters are optional.

```bash theme={null}
# All public products
curl https://api.mutasib.com/api/v1/public/shops/42/products/

# With search and category filter
curl "https://api.mutasib.com/api/v1/public/shops/42/products/?search=olive+oil&category_id=5"
```

Returns only the products where `is_public: true`.

## Nearby shop discovery

Customers can search for shops within a geographic radius using the nearby endpoint. This is useful for local discovery features in mobile apps or maps.

```bash theme={null}
# Find all shops within 10 km of Algiers city centre
curl "https://api.mutasib.com/api/v1/public/shops/nearby/?lat=36.7&lng=3.05&radius=10"
```

| Parameter | Type  | Default | Description                    |
| --------- | ----- | ------- | ------------------------------ |
| `lat`     | float | —       | Latitude of the search origin  |
| `lng`     | float | —       | Longitude of the search origin |
| `radius`  | float | `10`    | Search radius in kilometres    |

The response returns shops sorted by `distance_km` in ascending order, so the closest shop appears first.

For your shop to appear in nearby results, it must have its `latitude` and `longitude` fields set.

## Setting your shop's location

Update your shop's coordinates with a `PATCH` request. You only need to do this once (or whenever your shop moves).

```bash theme={null}
curl -X PATCH https://api.mutasib.com/api/v1/shops/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 36.7372,
    "longitude": 3.0865
  }'
```

Once coordinates are saved, your shop will appear in nearby searches automatically.

<Accordion title="Tips for better search visibility">
  * **Write descriptive product names.** The search index matches against product names and descriptions, so clear names like "Full-Fat Labneh 500g" rank better than "LBN-500".
  * **Use consistent categories.** Products grouped under recognised categories (e.g. `dairy`, `bakery`, `beverages`) benefit from category-filtered searches.
  * **Keep prices up to date.** Customers often filter by price range — stale prices lead to confusion and abandoned visits.
  * **Add your location.** Even if you don't have a delivery service, appearing in nearby searches drives walk-in traffic.
</Accordion>