Getting started

Use the HFSAA Public API.

Request an API key

Start with a rate-limited test key for development—no developer account required.

Request API access

Base URLs

The v1 API is read-only and requires an API key. Use the URL that matches the environment shown when the key is claimed.

Key	Base URL
Test (hfsaa_test_…)	https://hfsaa-public-api-staging.idris-ocasio.workers.dev
Production (hfsaa_live_…)	https://api.hfsaa.org

Get an API key

Open the API access application, choose test or production access, and verify your email address. HFSAA manually approves or denies each request.

Test access does not require an account. A test key does not expire automatically, but it only works at the test base URL and is subject to its assigned rate and monthly request limits. Production access is reviewed separately and may require a paid capacity agreement.

Approved applicants receive a short-lived, one-time claim link. The raw API key is shown once, so store it in a server-side secret manager. Never include it in browser or mobile application code.

Core resource

Location is the canonical resource. Every currently certified restaurant, meat market, and dining hall has an opaque HFSAA location ID and a type.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "restaurant",
  "name": "Example Restaurant",
  "verification_url": "https://hfsaa-public-locator.pages.dev/?certificate_id=HFSAA-R-EXAMPLE",
  "certification_status": "certified",
  "chapter_name": "Example Chapter",
  "address": "123 Main Street",
  "city": "Example City",
  "state": "NY",
  "zip_code": "10001",
  "cuisine_type": "Mediterranean",
  "google_place_id": "ChIJ..."
}

chapter_name, address, city, state, zip_code, cuisine_type, and google_place_id may each be null. Applications should omit or adapt any corresponding UI when a value is unavailable.

Make a request

Every directory-data endpoint requires an API key. Send it in the Authorization header on every request; query-string keys and anonymous requests are not supported.

curl "$HFSAA_API_BASE_URL/v1/locations?type=restaurant&limit=25" \
  -H "Authorization: Bearer $HFSAA_API_KEY"

The production API accepts only production keys, and the test API accepts only test keys. A missing, malformed, unknown, or wrong-environment key returns HTTP 401. A revoked key returns HTTP 403. The public /health check and developer application, email-verification, key-claim, and accountless management pages do not require an API key; they do not expose directory data and use their own one-time-token or session protections where applicable.

Filtering and pagination

GET /v1/locations supports filters for type, state, city, ZIP code, chapter, and free-text search. Lists use a limit and cursor-based cursor parameter.

Every list response includes a dataset_version. A cursor is bound to that immutable version, and subsequent pages repeat the same version even if HFSAA publishes a newer dataset while you paginate. Keep the same filters with every page request and treat cursors as opaque.

Superseded versions remain available for at least seven days. If a cursor’s version has expired, the API returns HTTP 410; restart pagination without the expired cursor.

Dataset snapshots

GET /v1/dataset returns the current dataset_version, UTC generated_at time, exact location_count, a SHA-256 checksum, and a version-specific download_url.

The checksum covers the exact bytes returned by that URL. Use the version-specific URL rather than an unversioned download when reproducibility matters.

Caching

API data may be cached for no more than one hour. Responses use Cache-Control: private, max-age=3600, must-revalidate, which permits a private application or browser cache while preventing shared caches from serving authenticated responses without running API-key checks and usage tracking.

After one hour, revalidate or fetch fresh data before displaying it as current HFSAA certification information. A versioned snapshot remaining available for cursor stability does not extend this one-hour caching allowance.

Rate limits and retries

Test keys default to 10 requests per minute and 1,000 requests per month. HFSAA can assign different limits during production review. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the monthly allowance.

When a per-minute or monthly limit is exceeded, the API returns HTTP 429 with a Retry-After header and a structured JSON error body.

Retry 429, 500, 502, 503, and 504 responses with bounded exponential backoff and jitter. Honor Retry-After whenever it is present. Correct 400 requests rather than retrying them unchanged.

Verification and attribution

When your product states or implies that a location is certified or halal verified by HFSAA, identify HFSAA and give users reasonable access to the exact verification_url returned for that location.

For example, this is one acceptable presentation:

Certified by <a href="location.verification_url">HFSAA</a>

The link can instead be associated with a badge, Learn more link, or another clearly related details element. No exact wording is required. In digital products the URL must be clickable; offline material may use a printed URL or QR code. See the data policy for caching, redistribution, freshness, and verification requirements.

Do not present HFSAA data in a way that implies HFSAA endorses your application.

Google Place IDs

When supplied, a google_place_id is an identifier only. If your application uses Google Places to look up photos, hours, maps, or other Google content, you are responsible for your own Google Maps Platform credentials, billing, attribution, and policy compliance.