v1Live

HalalAPI Docs

Complete reference for the Halal Locations API. Find halal restaurants by zip code or GPS coordinates, powered by Foursquare + OpenStreetMap.

Overview

What this API is and what it returns.

Base URL

halal-api.vercel.app

Protocol

HTTPS only

Format

JSON

HalalAPI is a REST API that searches for halal restaurants near a given location. It combines data from Foursquare Places and the OpenStreetMap community to give broader halal coverage than any single data source. Responses include halal certification status, alcohol policy, cuisine type, contact info, and distance.

Designed for:

Muslim restaurant finder and travel apps
Food delivery platforms serving halal-conscious users
AI agents and LLM tools needing halal food data
Maps and local discovery apps
Prayer time apps adding nearby halal food features

Quick Start

Make your first API call in under 2 minutes.

Step 1 — Get a free API key

Go to halal-api.vercel.app, enter your email address, and your key is generated instantly. No credit card required. Starts with 500 free requests/month.

Step 2 — Make your first request

curl "https://halal-api.vercel.app/api/v1/locations?zip=77024&radius=5" \
  -H "x-api-key: YOUR_API_KEY"

Step 3 — Parse the response

You'll receive a JSON object with a data array of restaurants and a meta object with totals and location info. See Response Format for full details.

Authentication

How to pass your API key.

Every request must be authenticated. There are two methods depending on how you access the API.

Method 1 — Direct access

Recommended

Pass your key in the x-api-key request header. Get your key at halal-api.vercel.app.

Request header

x-api-key: hk_your_api_key_here

Keys start with hk_ followed by a 48-character hex string.

Method 2 — Via RapidAPI

If accessing through RapidAPI marketplace, use your RapidAPI key and the RapidAPI gateway URL.

curl "https://halalapi.p.rapidapi.com/api/v1/locations?zip=77024" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: halalapi.p.rapidapi.com"

Security notes

Never expose your API key in client-side JavaScript or public repos
Store keys in environment variables (process.env.HALAL_API_KEY)
Each key is tied to an email address and a monthly request limit
If your key is compromised, contact baqirhzaidi5@gmail.com immediately

Base URL

Endpoints for direct and RapidAPI access.

Direct

Recommended

https://halal-api.vercel.app

No intermediary. Lower latency. You keep 100% of revenue.

RapidAPI Gateway

https://halalapi.p.rapidapi.com

Via RapidAPI marketplace. Requires RapidAPI subscription.

Data Sources

Where the halal data comes from.

Every request queries both sources in parallel and merges results. Duplicates are removed by name matching.

Foursquare Places

Primary

Searches Foursquare's 100M+ global places database using the keyword halal filtered by location and radius.

Returns up to 50 results per request. Places from this source appear with source: "foursquare" and a hex fsq_id.

Halal certification is unverified by default unless enriched by community data in our database.

OpenStreetMap (Overpass API)

Community Verified

Queries the OpenStreetMap Overpass API for nodes tagged with diet:halal=yes or diet:halal=only within the search radius.

These are community-contributed tags added by Muslim contributors worldwide. Places from this source appear with source: "openstreetmap" and an osm_ prefixed ID.

diet:halal=yes → halal_certification: "community-verified"
diet:halal=only → halal_certification: "halal-only"

Deduplication

Results from both sources are merged and deduplicated by restaurant name (case-insensitive). If a place exists in both Foursquare and OSM, the Foursquare version is kept and the OSM entry is discarded to avoid duplicates.

Endpoints

All available API endpoints.

GET/api/v1/locationsv1

Search for halal restaurants near a given location. Returns merged, deduplicated results from Foursquare and OpenStreetMap sorted by distance.

Requires authRate limitedJSON response

More endpoints coming soon: POST /api/v1/locations/submit for community submissions.

Parameters

All query parameters for GET /api/v1/locations.

Parameter	Type	Required	Default	Description
zip	string	one of*	—	Zip or postal code. Works globally. E.g. 77024, EC1A 1BB, 75008
lat	number	one of*	—	Latitude. Float. Use with lng. E.g. 29.7604
lng	number	one of*	—	Longitude. Float. Use with lat. E.g. -95.3698
radius	number	no	5	Search radius in miles. Min: 1. Max: 31.
min_rating	number	no	0	Minimum community rating filter (0–5 scale).
certified_only	boolean	no	false	If true, only return community-verified or halal-only places from OSM.

* You must provide either zip OR both lat and lng. Providing neither returns a 400 error.

Parameter examples

GET /api/v1/locations?zip=77024

Response Format

Structure of a successful JSON response.

{
  "data": [
    {
      // --- Identity ---
      "fsq_id": "4be444f4cf200f47d3b2113c",   // Foursquare hex ID
      "name": "Empire Turkish Grill",
      "source": "foursquare",                  // "foursquare" | "openstreetmap"

      // --- Location ---
      "address": "12448 Memorial Dr, Houston, TX 77024",
      "city": "Houston",
      "state": "TX",
      "postcode": "77024",
      "latitude": 29.771,
      "longitude": -95.513,
      "distance_meters": 3561,

      // --- Category ---
      "cuisine_type": "Turkish Restaurant",
      "chain": null,

      // --- Contact ---
      "phone": "(713) 827-7475",
      "website": "http://www.empiretrgrill.com",
      "instagram": null,

      // --- Halal classification ---
      "halal_certification": "unverified",
      "halal_status": "UNVERIFIED",            // FULL | PARTIAL | VERBALLY_CONFIRMED | UNVERIFIED
      "alcohol_served": null,                  // true | false | null
      "cross_contamination_protocols": null,   // true | false | null

      // --- Official certification ---
      "certification": {
        "is_certified": false,
        "certified_by": null,                  // e.g. "HFSAA", "HMC", "IFANCA", "MUI"
        "certificate_id": null,
        "expiry_date": null,
        "last_verified_timestamp": null
      },

      "community_rating": null,
      "verified": false
    },
    {
      // Fully certified example
      "fsq_id": "4be555abc",
      "name": "Al-Baik Restaurant",
      "source": "foursquare",
      "halal_status": "FULL",
      "alcohol_served": false,
      "cross_contamination_protocols": true,
      "certification": {
        "is_certified": true,
        "certified_by": "HFSAA",
        "certificate_id": "102938",
        "expiry_date": "2027-01-01",
        "last_verified_timestamp": "2026-06-01T12:00:00Z"
      },
      "verified": true
    },
    {
      // OSM example
      "fsq_id": "osm_987654321",
      "name": "Bismillah Restaurant & Cafe",
      "source": "openstreetmap",
      "halal_status": "FULL",
      "halal_certification": "community-verified",
      "alcohol_served": false,
      "cross_contamination_protocols": null,
      "certification": {
        "is_certified": false,
        "certified_by": null,
        "certificate_id": null,
        "expiry_date": null,
        "last_verified_timestamp": null
      },
      "verified": true
    }
  ],
  "meta": {
    "total": 23,
    "location": { "lat": 29.7724614, "lng": -95.5119247 },
    "radius_miles": 5
  }
}

Response Fields

Field	Type	Nullable	Description
fsq_id	string	no	Unique place ID. Foursquare: hex string. OSM: osm_{nodeId}
name	string	no	Restaurant name
source	string	no	foursquare or openstreetmap
address	string	yes	Full formatted address string
city	string	yes	City name
state	string	yes	State abbreviation e.g. TX, NY
postcode	string	yes	Zip/postal code
latitude	number	yes	Latitude coordinate
longitude	number	yes	Longitude coordinate
distance_meters	number	yes	Distance from search point in meters
cuisine_type	string	yes	Category e.g. Turkish Restaurant, fast_food
chain	string	yes	Chain name if part of a chain, null otherwise
phone	string	yes	Phone number
website	string	yes	Website URL
instagram	string	yes	Instagram handle (Foursquare only)
halal_certification	string	no	unverified · community-verified · halal-only (legacy)
halal_status	string	no	FULL · PARTIAL · VERBALLY_CONFIRMED · UNVERIFIED
alcohol_served	boolean	yes	true/false if known, null if unknown
cross_contamination_protocols	boolean	yes	true if separate grills/fryers for halal meat, null if unknown
certification.is_certified	boolean	no	true if officially certified by a halal body
certification.certified_by	string	yes	Certifying body e.g. HFSAA, HMC, IFANCA, MUI
certification.certificate_id	string	yes	Official certificate number
certification.expiry_date	string	yes	Certificate expiry (YYYY-MM-DD)
certification.last_verified_timestamp	string	yes	ISO 8601 timestamp of last verification
community_rating	number	yes	Community rating 0–5, null if not yet rated
verified	boolean	no	true if enriched with community data from our database

Halal Fields

Understanding halal_certification, serves_alcohol, and verified.

halal_status — nuanced halal classification

Value	Meaning
FULL	Entire menu is halal. No pork or alcohol on premises. Highest trust level.
PARTIAL	Some halal items available (e.g. only the chicken), but non-halal items or pork are also served in the same kitchen.
VERBALLY_CONFIRMED	Staff claims food is halal but no official certificate is posted or verifiable.
UNVERIFIED	No halal status data available. Restaurant appears halal by name/category only.

alcohol_served

Value	Meaning
false	Confirmed alcohol-free. Safe for users who avoid restaurants that serve alcohol.
true	Alcohol is served on premises. Some users will avoid even if the food is halal.
null	Unknown. No data available.

cross_contamination_protocols

true means the kitchen uses separate grills, fryers, and utensils for halal meat versus non-halal meat or pork. Critical for users with strict halal standards. null if unknown.

certification object

Field	Description
is_certified	true if an official halal certificate exists
certified_by	Name of certifying body: HFSAA, HMC, IFANCA, MUI, JAKIM, etc.
certificate_id	Official certificate number for verification
expiry_date	Certificate expiry date in YYYY-MM-DD format
last_verified_timestamp	When we last verified this certificate (ISO 8601)

Common certifying bodies: HFSAA (US), HMC (UK), IFANCA (US/Global), MUI (Indonesia), JAKIM (Malaysia), HFA (UK)

verified

true if the place has been enriched with data from our community database. All OSM places are verified: true. Foursquare places are verified: false unless manually enriched.

Filtering

How to filter results for specific use cases.

Only show community-verified halal spots

Use certified_only=true to filter out unverified Foursquare results and only return OSM-tagged places.

GET /api/v1/locations?zip=77024&certified_only=true

Filter by rating

Use min_rating to only return places with a community rating at or above the threshold.

GET /api/v1/locations?zip=77024&min_rating=4

Identify alcohol-free restaurants in code

const alcoholFree = data.data.filter(r => r.serves_alcohol === false);

Sort by distance in code

const sorted = data.data.sort((a, b) => a.distance_meters - b.distance_meters);

Error Codes

All possible error responses and how to handle them.

Status	Error message	Cause	Fix
400	Missing x-api-key header	No API key in request	Add x-api-key header
400	Provide either ?zip= or ?lat=&lng=	No location param	Add zip or lat+lng
400	Invalid zip code	Zip couldn't be geocoded	Check the zip code is valid US
401	Invalid API key	Key not found in database	Check your key is correct
429	Rate limit exceeded	Monthly limit reached	Upgrade your plan
500	Internal server error	Server-side failure	Retry or contact support

Error response shape

{ "error": "Error message here" }

Rate Limits

Usage limits per plan, resets, and warnings.

Plan	Requests/month	Price	Available on
Free	500	$0/mo	Direct + RapidAPI
Starter	2,000	$9/mo	Direct + RapidAPI
Pro	10,000	$25/mo	Direct + RapidAPI
Business	100,000	$59/mo	Direct + RapidAPI

Monthly reset

Usage resets to 0 on the 1st of every month automatically.

Warning emails

You get an email at 80% and 90% usage so you're never surprised.

Hard limit

At 100% usage all requests return 429 until the next reset or upgrade.

Upgrade your plan →

Code Examples

Full working examples in popular languages.

Search by zip code and print names

import requests

API_KEY = "YOUR_API_KEY"

res = requests.get(
    "https://halal-api.vercel.app/api/v1/locations",
    params={"zip": "77024", "radius": 5},
    headers={"x-api-key": API_KEY}
)

data = res.json()
for place in data["data"]:
    print(f"{place['name']} — {place['halal_certification']} ({place['distance_meters']}m)")

Get only alcohol-free, community-verified places near coordinates

import requests

res = requests.get(
    "https://halal-api.vercel.app/api/v1/locations",
    params={
        "lat": 29.7604,
        "lng": -95.3698,
        "radius": 3,
        "certified_only": "true"
    },
    headers={"x-api-key": "YOUR_API_KEY"}
)

data = res.json()
# Further filter for confirmed alcohol-free
clean = [p for p in data["data"] if p["serves_alcohol"] == False]
print(f"Found {len(clean)} alcohol-free verified halal spots")

FAQ

Common questions from developers and AI agents.

What countries does the API support?

The API works globally. Pass any postal code (US zip, UK postcode, etc.) or lat/lng coordinates anywhere in the world. OSM community coverage is strongest in North America and Europe, but growing worldwide. Foursquare covers 100M+ places globally.

How accurate is the halal data?

Foursquare results are based on restaurant name and category keywords — they are unverified and may include non-halal places. OpenStreetMap results are tagged by community contributors and are generally more reliable, but are not official certifications.

Why might the same restaurant appear twice?

Deduplication is done by name match. If a restaurant has slightly different names across Foursquare and OpenStreetMap (e.g. 'Halal Guys' vs 'The Halal Guys'), both may appear. We're improving this over time.

What does fsq_id starting with osm_ mean?

It means the result came from OpenStreetMap, not Foursquare. The ID format is osm_ followed by the OSM node ID. These IDs are stable as long as the OSM node exists.

How do I use this with an AI agent or LLM?

Pass your API key as an environment variable and call the endpoint with a zip or coordinates. The JSON response is structured to be easily parsed. Filter with certified_only=true for higher-confidence results when recommending food to users.

Does the radius parameter affect both data sources?

Yes. Both Foursquare and OpenStreetMap queries use the same radius in meters (converted from your miles input). The maximum is capped at 50,000 meters (~31 miles) for both sources.

Why is my response slow sometimes?

The API queries Foursquare and OpenStreetMap in parallel. OpenStreetMap's Overpass API can occasionally be slow (2–5 seconds). If OSM times out, the response still returns Foursquare results — OSM failures are handled gracefully.