Introduction

Welcome to the Halal Bites API documentation. The API provides programmatic access to the world's most comprehensive verified halal restaurant and food truck database.

Our API uses predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs. The base URL for all endpoints is https://api.halalbites.co.

Note: Certain advanced filtering input fields across our endpoints are only available to users on paid plans. Refer to your billing dashboard for more details.

Authentication

The Halal Bites API uses API keys to authenticate requests. You can view and manage your API keys in your Developer Dashboard.

Authentication to the API is performed via a custom header. Provide your API key in the x-api-key header.

Keep your API keys secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

POST

Get Restaurant List

Fetch a list of restaurants matching search, location, and filter criteria.

Certain advanced parameters (e.g. specific cuisine_id filtering) are only available on paid plans.

Error States

Validation Errors: Fails if any of the required fields are missing or strictly invalid: is_open_now, is_food_truck, is_certified, is_alcohol_free, is_fully_halal, is_zabiha_halal, lat, lng, user_lat, user_lng, radius, limit, offset, or map_location_datetime.
500 Internal Server Error: Throws an error "Invalid map_location_datetime" if the provided string cannot be parsed into a valid date and time format.

cURL Example (/list)

curl -X POST "https://api.halalbites.co/list" \
  -H "x-api-key: hb_prd_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{                                                                                                                                                     
    "is_open_now": true,        
    "is_food_truck": false,
    "is_certified": false,
    "is_alcohol_free": true,
    "is_fully_halal": true,
    "is_zabiha_halal": false,
    "lat": 40.7128,
    "lng": -74.0060, 
    "user_lat": 40.7128,
    "user_lng": -74.0060,
    "radius": 10,
    "limit": 25,     
    "offset": 0,     
    "map_location_datetime":"2023-10-25T12:00:00Z",
    "cuisine_id": [1, 2],
    "rating": [4, 5],
    "sort_by": "distance"
}'

POST

Get List Map View

Fetch restaurants specifically optimized for map-based visualizations, taking corner points bounding boxes.

Certain advanced attributes require a paid plan.

Error States

Validation Errors: Fails if required fields are missing or not matching expected types/values. Notably, many boolean fields here expect 0 or 1 instead of true/false. corner_points, user_latitude, user_longitude, and map_location_datetime are also required.
500 Internal Server Error (Parsing Error): Throws an invalid date error if the map_location_datetime cannot be parsed into a proper date.

cURL Example (/list-map)

curl -X POST "https://api.halalbites.co/list-map" \
      -H "x-api-key: hb_prd_YOUR_API_KEY_HERE" \
      -H "Content-Type: application/json" \
      -d '{
        "is_open_now": true,
        "is_food_truck": false,
        "is_certified": false,
        "is_alcohol_free": true,
        "is_fully_halal": true,
        "is_zabiha_halal": false,
        "lat": 40.7128,
        "lng": -74.0060,
        "user_lat": 40.7128,
        "user_lng": -74.0060,
        "corner_points": [
          [40.8, -74.1],
          [40.8, -73.9],
          [40.6, -73.9],
          [40.6, -74.1]
        ],
        "map_location_datetime": "2023-10-25T12:00:00Z",
        "cuisine_id": [1, 2],
        "rating": [4, 5]
      }'

POST

Get Restaurant Details

Fetch detailed information for a single restaurant by ID.

Error States

Validation Errors: Fails if restaurant_id is missing or is not a number.
400 Bad Request: Occurs when the restaurant_id is valid, but the requested restaurant cannot be found.

cURL Example (/details)

curl -X POST "https://api.halalbites.co/details" \
  -H "x-api-key: hb_prd_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": 'DKWxk7wE'
}'

POST

Search Restaurants

Search for restaurants using a search term or location keywords.

Error States

Validation Errors: Fails if user_latitude, user_longitude, or is_current_location are missing. is_current_location strictly expects a 0 or 1.
500 Internal Server Error: Standard internal server error if the search request fails to process.

cURL Example (/search)

curl -X POST "https://api.halalbites.co/search" \
  -H "x-api-key: hb_prd_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "search_key": "halal guys",
    "user_latitude": "40.7580",
    "user_longitude": "-73.9855",
    "is_current_location": 0
}'

POST

Report Item

Submit a report against a restaurant. This is used for reporting a restaurant that is not halal, permanently closed, has wrong timings, incorrect cuisines, or other incorrect information.

Accepted Report Reasons

To automatically categorize the report on the backend, the reason string should ideally match one of the following exact phrases (though custom strings are also accepted and will be saved):

"1 - Duplicate listing"
"2 - This place is not halal"
"3 - Other"
"19 - Incorrect Information"
"20 - Update halal status"
"21 - Permanently closed"
"22 - Incorrect name"
"23 - Incorrect hours"
"24 - Cuisine is wrong or incomplete"
"25 - Incorrect location or address"

Error States

400/500 Validation Error: Fails if restaurant_id or reason are missing from the request body.
500 Internal Server Error (Creation Failure): Returned if the system encounters an error and fails to successfully save the report in the database.

cURL Example (/report)

curl -X POST "https://api.halalbites.co/report" \
  -H "x-api-key: hb_prd_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "V1StGXR8",
    "reason_id": 21,
    "reason": "Restaurant Closed"
}'

Error Handling

Here are the potential error states for each of the endpoints in the Public API.

Global Error States

These error states apply to all public API endpoints and are triggered by the application-level or route-level middleware before the controllers even execute:

403 Forbidden: Returns a 403 error if the request originates from an unauthorized source or is missing required API security headers.
400/500 Validation Error: Returned if the request payload does not match the strict schema requirements for an endpoint. A validation error is thrown containing the specific field that failed (e.g., "lat" is required).
401 Unauthorized (Conditional): While many endpoints allow unauthenticated access, if an authorization token is provided but is malformed, expired, or otherwise invalid, a 401 authorization error is returned.
429 Too Many Requests: API Rate Limiting will return a 429 Too Many Requests error if your API key exceeds its allotted usage limits or quota.
500 Internal Server Error: An unexpected system error occurred. Returns a 500 status code when an internal service or process fails.