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 100 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*	—	US zip code. E.g. 77024, 10001, 60601
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,                 // distance from search point

      // --- Category ---
      "cuisine_type": "Turkish Restaurant",    // from Foursquare or OSM amenity tag
      "chain": null,                           // chain name if part of a chain

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

      // --- Halal data ---
      "halal_certification": "unverified",     // see Halal Fields section
      "serves_alcohol": null,                  // true | false | null
      "community_rating": null,                // 0–5 float | null
      "verified": false                        // true if enriched with community data
    },
    {
      // OSM example — community-verified
      "fsq_id": "osm_987654321",               // OSM node ID prefixed with osm_
      "name": "Bismillah Restaurant & Cafe",
      "source": "openstreetmap",
      "address": "1234 Hillcroft Ave, Houston, TX",
      "city": "Houston",
      "state": "TX",
      "postcode": null,
      "latitude": 29.714,
      "longitude": -95.498,
      "distance_meters": 4200,
      "cuisine_type": "restaurant",
      "chain": null,
      "phone": null,
      "website": null,
      "instagram": null,
      "halal_certification": "community-verified",
      "serves_alcohol": false,
      "community_rating": null,
      "verified": true
    }
  ],
  "meta": {
    "total": 23,                               // total results returned
    "location": {
      "lat": 29.7724614,                       // resolved lat (from zip or input)
      "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
serves_alcohol	boolean	yes	false if confirmed no alcohol, null if unknown
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_certification — possible values

Value	Source	Meaning
unverified	Foursquare	Restaurant appears halal by name/category but has not been verified by the community.
community-verified	OpenStreetMap	Tagged `diet:halal=yes` by community contributors. Serves halal food among other options.
halal-only	OpenStreetMap	Tagged `diet:halal=only`. The restaurant exclusively serves halal food.

serves_alcohol — possible values

Value	Meaning
false	Confirmed alcohol-free. Tagged drink:alcohol=no in OSM or verified by community.
true	Confirmed serves alcohol.
null	Unknown. No data available from either source.

verified

true if the place has been enriched with data from our community database (halal certification, alcohol policy, or community rating). 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	100	$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?

Currently the API supports the United States only. The zip code geocoder uses US postal codes. Coordinates anywhere in the world will work for Foursquare results, but OSM coverage outside the US may be limited.

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.