Make Your Mutasib Shop Discoverable with Public Search

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.

Public search visibility is controlled from the Mutasib dashboard. This guide focuses on the endpoints that read from the public marketplace.

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.

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

# 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

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.

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

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

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.

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.

Get Started

Core Concepts

Guides

Make Your Mutasib Shop Discoverable with Public Search

Public search endpoints

Search across all shops

List all visible shops

Get a single shop’s details

List a shop’s public products

Nearby shop discovery

Setting your shop’s location

​Public search endpoints

​Search across all shops

​List all visible shops

​Get a single shop’s details

​List a shop’s public products

​Nearby shop discovery

​Setting your shop’s location

Public search endpoints

Search across all shops

List all visible shops

Get a single shop’s details

List a shop’s public products

Nearby shop discovery

Setting your shop’s location