🚀 Quick start

Public endpoints are rate-limited per IP (30 req/hr). For higher limits, create a free account and generate an API key from your dashboard.

curl -H "X-API-Key: YOUR_KEY" \
  "https://zipcodes.luxylushdeals.store/api/?endpoint=search&q=lahore"

🔑 Authentication

Pass your API key via:

• Header: X-API-Key: YOUR_KEY
• Header: Authorization: Bearer YOUR_KEY
• Query: ?api_key=YOUR_KEY

📚 Endpoints

curl "https://zipcodes.luxylushdeals.store/api/?endpoint=health"

curl "https://zipcodes.luxylushdeals.store/api/?endpoint=search&q=karachi"

curl "https://zipcodes.luxylushdeals.store/api/?endpoint=postal&code=44000&country=PK"

curl "https://zipcodes.luxylushdeals.store/api/?endpoint=countries"

curl "https://zipcodes.luxylushdeals.store/api/?endpoint=cities&country=IN"

curl "https://zipcodes.luxylushdeals.store/api/?endpoint=stats"

⏱️ Rate limits

Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

📦 Response format

{
  "query": "lahore",
  "total": 8,
  "results": [
    {
      "postal_code": "54000",
      "area_name": "Lahore GPO",
      "city": "Lahore",
      "state": "Punjab",
      "country_code": "PK"
    }
  ],
  "_meta": {
    "status": 200,
    "timestamp": "2025-11-15T10:30:00+00:00",
    "api_version": "v1",
    "elapsed_ms": 12
  }
}

📥 CSV Import (Admin)

Admins can bulk-import postal codes via CSV. Required columns: country_code,state,city,postal_code,area (area optional).

🛠 SDKs & Examples

fetch('https://zipcodes.luxylushdeals.store/api/?endpoint=search&q=mumbai',{
  headers:{'X-API-Key':'YOUR_KEY'}
}).then(r=>r.json()).then(console.log);

$ctx = stream_context_create([
 'http'=>['header'=>"X-API-Key: YOUR_KEY"]
]);
$r = file_get_contents(
 'https://zipcodes.luxylushdeals.store/api/?endpoint=postal&code=400001',
 false, $ctx);
print_r(json_decode($r, true));

import requests
r = requests.get('https://zipcodes.luxylushdeals.store/api/',
  params={'endpoint':'search','q':'noida'},
  headers={'X-API-Key':'YOUR_KEY'})
print(r.json())