Balkan Mosques
API

Overview

The Balkan Mosques API provides structured location data for mosques across the Balkan region. Every record includes the mosque name, city, address, and GPS coordinates (latitude and longitude) for use in maps and mobile applications.

All endpoints are read-only and require an API key passed in the request header. Keys are issued and managed by the API author.

Authentication

Every request must include your API key in the x-api-key request header. Requests with a missing or invalid key receive a 401 response.

GET /api/mosques
Host: xhamia-api.vercel.app
x-api-key: xhamia_live_your_key_here

To request an API key, contact the author directly.

Base URL

All endpoints are relative to this base URL. The API is served over HTTPS only.

List mosques

Returns a paginated list of all mosques. Defaults to 50 results per page.

Example request

curl https://xhamia-api.vercel.app/api/mosques \
  -H "x-api-key: xhamia_live_your_key_here"

Example response

{
  "success": true,
  "meta": {
    "total": 2372,
    "page": 1,
    "limit": 50,
    "totalPages": 48
  },
  "data": [
    {
      "id": "001",
      "name": "Xhamia Ahmetaq",
      "city": "Ahmetaq, Tiranë",
      "address": "Rruge fshati, qender",
      "lat": 41.433916,
      "lng": 19.682254
    }
  ]
}

Get mosque by ID

Returns a single mosque matching the given id.

Parameters

Example request

curl "https://xhamia-api.vercel.app/api/mosques?id=743" \
  -H "x-api-key: xhamia_live_your_key_here"

Example response

{
  "success": true,
  "data": {
    "id": 743,
    "name": "Xhamia Ethem Bej",
    "city": "Tiranë",
    "address": "Sheshi Skenderbej",
    "lat": 41.327793,
    "lng": 19.819346
  }
}

Filter by city

Returns all mosques in a given city. The match is case-insensitive and partial — searching tiran will match Tiranë.

Example request

curl "https://xhamia-api.vercel.app/api/mosques?city=Shkodër" \
  -H "x-api-key: xhamia_live_your_key_here"

Filter by name

Returns mosques whose name contains the given string. Case-insensitive partial match.

Example request

curl "https://xhamia-api.vercel.app/api/mosques?name=Plumbit" \
  -H "x-api-key: xhamia_live_your_key_here"

Pagination

All list endpoints support pagination using the page and limit query parameters.

Example

GET /api/mosques?city=Tiranë&page=2&limit=20

Response format

All responses are JSON. Successful responses always include "success": true and a data field. List responses additionally include a meta object with pagination details. Error responses include "success": false and an error string describing the problem.

Error codes

Mosque object