> ## Documentation Index > Fetch the complete documentation index at: https://hfsaa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List locations > Returns HFSAA-certified directory locations across all supported types. ## OpenAPI ````yaml /openapi.yaml get /v1/locations openapi: 3.1.0 info: title: HFSAA Public API version: 1.2.2 description: > API-key protected access to HFSAA-certified restaurants, meat markets, and dining halls. Every directory-data route in the `/v1` namespace requires an API key; there are no anonymous data endpoints. Public health and developer-onboarding routes are explicitly marked with `security: []` and do not expose directory data. Developers can request test access without creating an account. Test keys do not expire automatically, but they are restricted to the test environment and quota. Successful data responses may be cached privately for no more than one hour. contact: name: HFSAA servers: - url: https://api.hfsaa.org description: Production - url: https://hfsaa-public-api-staging.idris-ocasio.workers.dev description: Test security: - ApiKeyAuth: [] paths: /v1/locations: get: tags: - Locations summary: List locations description: Returns HFSAA-certified directory locations across all supported types. operationId: listLocations parameters: - $ref: '#/components/parameters/Type' - $ref: '#/components/parameters/State' - $ref: '#/components/parameters/City' - $ref: '#/components/parameters/ZipCode' - $ref: '#/components/parameters/Chapter' - $ref: '#/components/parameters/Search' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of locations. headers: Cache-Control: $ref: '#/components/headers/DataCacheControl' content: application/json: schema: $ref: '#/components/schemas/LocationList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '410': $ref: '#/components/responses/Expired' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/ServerError' components: parameters: Type: name: type in: query description: Restrict results to a location type. schema: $ref: '#/components/schemas/LocationType' State: name: state in: query description: Filter by two-letter U.S. state or territory code. schema: type: string minLength: 2 maxLength: 2 example: NY City: name: city in: query description: Filter by city name. schema: type: string example: New York ZipCode: name: zip_code in: query description: Filter by ZIP or postal code. schema: type: string example: '10001' Chapter: name: chapter in: query description: Filter by chapter name. schema: type: string example: New York Search: name: q in: query description: Search location names and directory fields. schema: type: string maxLength: 100 example: halal grill Limit: name: limit in: query description: Maximum number of results returned in one page. schema: type: integer minimum: 1 maximum: 100 default: 25 Cursor: name: cursor in: query description: >- Opaque, dataset-version-bound cursor returned by a prior list response. Keep the same filters when requesting the next page. Superseded versions remain available for at least seven days; an expired cursor returns HTTP 410. schema: type: string headers: DataCacheControl: description: >- Private caching is permitted for at most one hour. Revalidate after expiry; shared caches must not store authenticated responses. schema: type: string example: private, max-age=3600, must-revalidate schemas: LocationList: type: object additionalProperties: false required: - dataset_version - data - pagination properties: dataset_version: type: string description: >- Opaque immutable dataset version used for every page in this pagination sequence. data: type: array items: $ref: '#/components/schemas/Location' pagination: $ref: '#/components/schemas/Pagination' LocationType: type: string enum: - restaurant - meat_market - dining_hall Location: type: object additionalProperties: false required: - id - type - name - verification_url - certification_status properties: id: type: string description: Opaque HFSAA location identifier. example: 550e8400-e29b-41d4-a716-446655440000 type: $ref: '#/components/schemas/LocationType' name: type: string example: Example Restaurant verification_url: type: string format: uri description: >- Official HFSAA verification page for this location. When stating or implying HFSAA certification, identify HFSAA and provide reasonable access to this exact URL. example: >- https://hfsaa-public-locator.pages.dev/?certificate_id=HFSAA-R-EXAMPLE certification_status: type: string description: >- Public certification state. Only certified locations are returned in v1. example: certified chapter_name: type: - string - 'null' description: Associated HFSAA chapter, or null when unavailable. example: New York address: type: - string - 'null' description: Street address, or null when unavailable. example: 123 Main Street city: type: - string - 'null' description: City, or null when unavailable. example: New York state: type: - string - 'null' description: State or territory code, or null when unavailable. example: NY zip_code: type: - string - 'null' description: ZIP or postal code, or null when unavailable. example: '10001' cuisine_type: type: - string - 'null' description: HFSAA directory classification, or null when unavailable. example: Mediterranean google_place_id: type: - string - 'null' description: >- Google Place ID identifier, or null when unavailable. This API does not provide Google content. example: ChIJd8BlQ2BZwokRAFUEcm_qrcA Pagination: type: object additionalProperties: false required: - limit properties: limit: type: integer example: 25 next_cursor: type: - string - 'null' description: >- Dataset-version-bound cursor for the next page, or null when no more results exist. Error: type: object additionalProperties: false required: - error properties: error: type: object required: - code - message properties: code: type: string example: invalid_parameter message: type: string example: limit must be between 1 and 100. responses: BadRequest: description: The request contains an invalid parameter. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The Bearer credential is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The API key is recognized but has been revoked or is not permitted to access the resource. content: application/json: schema: $ref: '#/components/schemas/Error' Expired: description: The requested cursor or immutable dataset version has expired. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: The API key's per-minute or monthly allowance was exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: >- The service or an upstream dependency could not complete the request. Retry with exponential backoff and jitter. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: The service is temporarily unavailable. Retry after the indicated delay. headers: Retry-After: description: Seconds to wait before retrying when known. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: hfsaa_test_... or hfsaa_live_... description: 'Use the API key as `Authorization: Bearer `.' ````