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 Pin 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.wiapincode.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://wiapincode.com/map/852-623-518-816"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-08-22T10:30:00Z",
    "api_version": "2.0"
  }
}
                    Convert WIA Pin Code back to coordinates and location details
| Parameter | Type | Required | Description | 
|---|---|---|---|
wia_code | 
                            string | Required | WIA Pin Code (e.g., 852-623-518-816) | 
curl -X GET https://api.wiapincode.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.wiapincode.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 Pin Codes
| Parameter | Type | Required | Description | 
|---|---|---|---|
wia_code | 
                            string | Required | Center WIA Pin 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 Pin Code is correctly formatted
curl -X GET https://api.wiapincode.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 Pin Codes
curl -X POST https://api.wiapincode.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.wiapincode.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 Pin 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 Pin 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 Pin 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.wiapincode.com/v2'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    
    def encode(self, latitude, longitude, **kwargs):
        """Convert coordinates to WIA Pin 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 Pin 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 Pin Code: {result['data']['wia_code_full']}")
# Decode WIA Pin 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.wiapincode.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 Pin 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 Pin Code format is incorrect | 
QUOTA_EXCEEDED | 
                        402 | Daily/monthly quota exceeded | 
SERVER_ERROR | 
                        500 | Internal server error | 
npm install wia-code
                pip install wiapincode
                composer require wia/code
                Coming Soon
                Coming Soon
                Coming Soon
                Receive real-time notifications for events
encode.success - WIA Pin Code successfully generateddecode.success - WIA Pin 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 Pin 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@wiapincode.com for details.