QNAS API Documentation

Qatar National Address System utility service by NBOX.qa. This API provides address lookup and zone identification capabilities for Qatar addresses.

📍

Address Search

Look up coordinates for any Qatar address using zone, street, and building numbers.

🌎

Zone Lookup

Find which zone contains a given GPS coordinate using polygon boundaries.

⚡

Cached Results

Responses are cached for faster subsequent lookups.

🔗

RESTful JSON

Simple REST API returning JSON responses.

Base URL

All API requests should be made to:

http://qnas.nbox.qa

Authentication

All API endpoints require Bearer token authentication, except for public endpoints (/, /docs, /health).

Request Header

Include the following header in all API requests:

Authorization: Bearer YOUR_API_TOKEN

Example with cURL

curl -H "Authorization: Bearer YOUR_API_TOKEN" "http://qnas.nbox.qa/search?zone=61&street=123&building=45"

Authentication Errors

401 Missing or invalid authentication token

{
  "success": false,
  "message": "Authorization header required"
}

Contact the API administrator to obtain your authentication token.

Quick Start

1

Search for an Address

Get GPS coordinates for a Qatar address:

curl -H "Authorization: Bearer YOUR_TOKEN" "http://qnas.nbox.qa/search?zone=61&street=123&building=45"

2

Look up a Zone

Find which zone contains coordinates:

curl -H "Authorization: Bearer YOUR_TOKEN" "http://qnas.nbox.qa/zone?lat=25.286106&lng=51.534817"

3

Check Service Health

Verify the API is running (no auth required):

curl "http://qnas.nbox.qa/health"

Search Address

GET /search

Search for a Qatar address and retrieve its GPS coordinates. Results are cached in the database for faster subsequent lookups.

Parameters

Name	Type	Required	Description
`zone`	string	Required	The zone number (e.g., "61")
`street`	string	Required	The street number (e.g., "123")
`building`	string	Required	The building number (e.g., "45")

Example Request

GET /search?zone=61&street=123&building=45

Success Response 200

{
  "success": true,
  "data": {
    "zone": "61",
    "street": "123",
    "building": "45",
    "lat": 25.286106,
    "lng": 51.534817,
    "cached": false
  }
}

Error Responses

400 Missing required parameters

{
  "success": false,
  "message": "Missing required parameters: zone, street, building"
}

404 Address not found in QNAS system

{
  "success": false,
  "message": "Address not found"
}

Zone Lookup

GET /zone

Get the zone information for given GPS coordinates. Uses point-in-polygon algorithm to determine which zone contains the coordinate.

Parameters

Name	Type	Required	Description
`lat`	number	Required	Latitude coordinate (e.g., 25.286106)
`lng`	number	Required	Longitude coordinate (e.g., 51.534817)

Example Request

GET /zone?lat=25.286106&lng=51.534817

Success Response 200

{
  "success": true,
  "data": {
    "zone_number": "61",
    "name_en": "Al Dafna",
    "name_ar": "الدفنة"
  }
}

Error Responses

400 Missing or invalid coordinates

404 Coordinates not within any known zone

Sync Zones

POST /sync/zones

Synchronize all zone data from the official QNAS API to the local database. This includes zone boundaries (polygons) for coordinate lookups. Administrative endpoint.

Parameters

No parameters required. Send an empty POST request.

Example Request

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" "http://qnas.nbox.qa/sync/zones"

Success Response 200

{
  "success": true,
  "message": "Zone sync completed",
  "synced": 98,
  "failed": 2
}

Sync Status

GET /sync/status

Get the current count of zones stored in the local database.

Example Request

GET /sync/status

Success Response 200

{
  "success": true,
  "zonesInDatabase": 98
}

Health Check

GET /health

Health check endpoint to verify the service is running.

Success Response 200

{
  "status": "ok"
}

Error Handling

All error responses follow a consistent JSON structure:

{
  "success": false,
  "message": "Human-readable error description",
  "error": "Technical details (only for 500 errors)"
}

HTTP Status Codes

Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid or missing parameters
401	Unauthorized - Missing or invalid authentication token
404	Not Found - Requested resource does not exist
500	Internal Server Error - Server-side processing error

Data Types

Coordinates

All coordinates use standard decimal degrees format:

Latitude: -90 to 90 (e.g., 25.286106)
Longitude: -180 to 180 (e.g., 51.534817)

Zone Numbers

Zone numbers in Qatar are typically 1-3 digit numbers represented as strings (e.g., "1", "61", "100").

Bilingual Support

Zone names are provided in both English (name_en) and Arabic (name_ar).