Universal Location Code System - Developer Documentation
Version 2.0 | RESTful APIForever Free
Lifetime Free
1M calls/month
Plan | Daily Limit | Rate Limit | Burst Limit | Concurrent Connections |
---|---|---|---|---|
Government/Public | Unlimited | Unlimited | Unlimited | Unlimited |
Individual (Free) | 100 requests | 1 req/sec | 10 requests | 1 |
Business Starter | 10,000 requests | 10 req/sec | 100 requests | 10 |
Enterprise Pro ($999) | 1,000,000 requests | 1,000 req/sec | 10,000 requests | 1,000 |
Custom Enterprise | Custom | Custom | Custom | Unlimited |
All API requests require authentication using an API key. Include your API key in the request header:
Authorization: Bearer YOUR_API_KEY X-WIA-API-Key: YOUR_API_KEY
Getting your API Key:
Convert latitude/longitude coordinates to WIA Code
Parameter | Type | Required | Description |
---|---|---|---|
latitude |
float | Required | Latitude (-90 to 90) |
longitude |
float | Required | Longitude (-180 to 180) |
country_code |
string | Optional | ISO country code (auto-detected if not provided) |
floor |
integer | Optional | Floor number for 3D positioning |
time |
string | Optional | Time in HHMM format for 4D positioning |
curl -X POST https://api.wiacode.com/v2/encode \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "latitude": 22.2783, "longitude": 114.1747, "country_code": "852", "floor": 55, "time": "1430" }'
{ "success": true, "data": { "wia_code": "852-623-518-816", "wia_code_full": "852-623-518-816.55.1430", "formatted": { "country": "852", "location": "623-518-816", "floor": 55, "time": "14:30" }, "precision_meters": 3, "qr_code": "data:image/png;base64,iVBORw0KGgoAAAA...", "google_maps_url": "https://maps.google.com/?q=22.2783,114.1747", "wia_map_url": "https://wiacode.com/map/852-623-518-816" }, "meta": { "request_id": "req_abc123", "timestamp": "2025-08-22T10:30:00Z", "api_version": "2.0" } }
Convert WIA Code back to coordinates and location details
Parameter | Type | Required | Description |
---|---|---|---|
wia_code |
string | Required | WIA Code (e.g., 852-623-518-816) |
curl -X GET https://api.wiacode.com/v2/decode/852-623-518-816 \ -H "Authorization: Bearer YOUR_API_KEY"
{ "success": true, "data": { "wia_code": "852-623-518-816", "coordinates": { "latitude": 22.2783, "longitude": 114.1747 }, "location": { "country": "Hong Kong", "country_code": "852", "city": "Central", "district": "Central and Western", "address": "IFC Tower, Central, Hong Kong" }, "precision_meters": 3, "timezone": "Asia/Hong_Kong", "elevation_meters": 5 } }
Process multiple locations in a single request (max 100)
curl -X POST https://api.wiacode.com/v2/batch \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "locations": [ {"latitude": 22.2783, "longitude": 114.1747}, {"latitude": 37.5665, "longitude": 126.9780}, {"latitude": 1.3521, "longitude": 103.8198} ] }'
Find nearby locations with WIA Codes
Parameter | Type | Required | Description |
---|---|---|---|
wia_code |
string | Required | Center WIA Code |
radius |
integer | Optional | Search radius in meters (default: 1000) |
type |
string | Optional | Filter by type (hotel, restaurant, hospital) |
limit |
integer | Optional | Max results (default: 20, max: 100) |
Validate if a WIA Code is correctly formatted
curl -X GET https://api.wiacode.com/v2/validate/852-623-518-816 \ -H "Authorization: Bearer YOUR_API_KEY"
{ "success": true, "data": { "is_valid": true, "format": "standard", "components": { "country_code": "852", "location_code": "623-518-816", "has_floor": false, "has_time": false } } }
Calculate distance between two WIA Codes
curl -X POST https://api.wiacode.com/v2/distance \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "852-623-518-816", "to": "852-623-380-815", "unit": "km" }'
const axios = require('axios'); class WIACodeAPI { constructor(apiKey) { this.apiKey = apiKey; this.baseURL = 'https://api.wiacode.com/v2'; } async encode(lat, lng, options = {}) { try { const response = await axios.post( `${this.baseURL}/encode`, { latitude: lat, longitude: lng, ...options }, { headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' } } ); return response.data; } catch (error) { console.error('Error encoding WIA Code:', error); throw error; } } async decode(wiaCode) { try { const response = await axios.get( `${this.baseURL}/decode/${wiaCode}`, { headers: { 'Authorization': `Bearer ${this.apiKey}` } } ); return response.data; } catch (error) { console.error('Error decoding WIA Code:', error); throw error; } } } // Usage const wia = new WIACodeAPI('YOUR_API_KEY'); // Encode coordinates wia.encode(22.2783, 114.1747, { floor: 55 }) .then(result => console.log(result)); // Decode WIA Code wia.decode('852-623-518-816') .then(result => console.log(result));
import requests import json class WIACodeAPI: def __init__(self, api_key): self.api_key = api_key self.base_url = 'https://api.wiacode.com/v2' self.headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } def encode(self, latitude, longitude, **kwargs): """Convert coordinates to WIA Code""" data = { 'latitude': latitude, 'longitude': longitude, **kwargs } response = requests.post( f'{self.base_url}/encode', headers=self.headers, json=data ) return response.json() def decode(self, wia_code): """Decode WIA Code to coordinates""" response = requests.get( f'{self.base_url}/decode/{wia_code}', headers=self.headers ) return response.json() def batch_encode(self, locations): """Encode multiple locations""" data = {'locations': locations} response = requests.post( f'{self.base_url}/batch', headers=self.headers, json=data ) return response.json() # Usage wia = WIACodeAPI('YOUR_API_KEY') # Encode single location result = wia.encode(22.2783, 114.1747, floor=55, time='1430') print(f"WIA Code: {result['data']['wia_code_full']}") # Decode WIA Code location = wia.decode('852-623-518-816') print(f"Coordinates: {location['data']['coordinates']}") # Batch encode locations = [ {'latitude': 22.2783, 'longitude': 114.1747}, {'latitude': 37.5665, 'longitude': 126.9780} ] batch_result = wia.batch_encode(locations) print(batch_result)
<?php class WIACodeAPI { private $apiKey; private $baseURL = 'https://api.wiacode.com/v2'; public function __construct($apiKey) { $this->apiKey = $apiKey; } public function encode($lat, $lng, $options = []) { $data = array_merge([ 'latitude' => $lat, 'longitude' => $lng ], $options); return $this->request('POST', '/encode', $data); } public function decode($wiaCode) { return $this->request('GET', "/decode/{$wiaCode}"); } private function request($method, $endpoint, $data = null) { $ch = curl_init($this->baseURL . $endpoint); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer ' . $this->apiKey, 'Content-Type: application/json' ]); if ($method === 'POST' && $data) { curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); } $response = curl_exec($ch); curl_close($ch); return json_decode($response, true); } } // Usage $wia = new WIACodeAPI('YOUR_API_KEY'); // Encode $result = $wia->encode(22.2783, 114.1747, ['floor' => 55]); echo "WIA Code: " . $result['data']['wia_code_full'] . "\n"; // Decode $location = $wia->decode('852-623-518-816'); print_r($location); ?>
{ "success": false, "error": { "code": "INVALID_COORDINATES", "message": "Latitude must be between -90 and 90", "details": { "field": "latitude", "value": 91.5 } }, "meta": { "request_id": "req_xyz789", "timestamp": "2025-08-22T10:30:00Z" } }
Error Code | HTTP Status | Description |
---|---|---|
INVALID_API_KEY |
401 | API key is missing or invalid |
RATE_LIMIT_EXCEEDED |
429 | Too many requests |
INVALID_COORDINATES |
400 | Coordinates are out of valid range |
INVALID_WIA_CODE |
400 | WIA Code format is incorrect |
QUOTA_EXCEEDED |
402 | Daily/monthly quota exceeded |
SERVER_ERROR |
500 | Internal server error |
npm install wia-code
pip install wiacode
composer require wia/code
Coming Soon
Coming Soon
Coming Soon
Receive real-time notifications for events
encode.success
- WIA Code successfully generateddecode.success
- WIA Code successfully decodedbatch.complete
- Batch processing completedquota.warning
- 80% of quota usedquota.exceeded
- Quota limit reached{ "event": "encode.success", "data": { "wia_code": "852-623-518-816", "coordinates": { "latitude": 22.2783, "longitude": 114.1747 } }, "timestamp": "2025-08-22T10:30:00Z", "signature": "sha256=abc123..." }
Join thousands of developers using WIA Code API for precision location services
You'll receive a 429 status code with a Retry-After
header indicating when you can retry.
Consider upgrading to Enterprise plan for higher limits.
Yes! Individual free tier can be used for commercial projects with 100 calls/day limit. For higher volume, consider the Enterprise plan at $999/month.
All plans provide ±3m accuracy. Enterprise custom plans can achieve ±1m ultra-precision with dedicated infrastructure.
Yes, all government and public institutions get unlimited free access forever. Simply sign up with a .gov domain email for automatic unlimited plan activation.
Enterprise Pro plans ($999/month) include white-label options. You can provide the service under your own brand. Contact sales@wiacode.com for details.