WIA Code API

Universal Location Code System - Developer Documentation

Version 2.0 | RESTful API

📊 API Pricing & Limits

🏛️ Government/Public
FREE

Forever Free

  • ✓ Complete system free
  • ✓ Unlimited WIA Code generation
  • ✓ Technical support included
  • ✓ Training materials provided
  • ✓ Unlimited API usage
  • ✓ Custom integration support
🏢 Enterprise API
$999

1M calls/month

  • ✓ Batch processing API
  • ✓ 99.9% SLA guarantee
  • ✓ Dedicated support team
  • ✓ Custom integration
  • ✓ Analytics dashboard
  • ✓ White-label options
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

Authentication

🔑 API Key Authentication

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:

  1. Sign up at wiacode.com/signup
  2. Verify your email address
  3. Navigate to Dashboard → API Keys
  4. Click "Generate New Key"
  5. Government domains (.gov) automatically get unlimited access

API Endpoints

POST https://api.wiacode.com/v2/encode NEW

Convert latitude/longitude coordinates to WIA Code

Request Parameters

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
JavaScript
Python
PHP
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"
  }'

Response Example

200 OK
{
  "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"
  }
}
GET https://api.wiacode.com/v2/decode/{wia_code}

Convert WIA Code back to coordinates and location details

Path Parameters

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"

Response Example

200 OK
{
  "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
  }
}
POST https://api.wiacode.com/v2/batch BETA

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}
    ]
  }'
GET https://api.wiacode.com/v2/nearby

Find nearby locations with WIA Codes

Query Parameters

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)
GET https://api.wiacode.com/v2/validate/{wia_code}

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"

Response Example

200 OK
{
  "success": true,
  "data": {
    "is_valid": true,
    "format": "standard",
    "components": {
      "country_code": "852",
      "location_code": "623-518-816",
      "has_floor": false,
      "has_time": false
    }
  }
}
POST https://api.wiacode.com/v2/distance

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"
  }'

Code Examples

JavaScript (Node.js)

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));

Python

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

<?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);
?>

Error Handling

Error Response Format

{
  "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"
  }
}

Common Error Codes

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

SDKs & Libraries

📦

JavaScript/Node.js

npm install wia-code
🐍

Python

pip install wiacode
🐘

PHP

composer require wia/code

Java

Coming Soon
🦀

Rust

Coming Soon
🐹

Go

Coming Soon

Webhooks & Events

WEBHOOK Your configured webhook URL NEW

Receive real-time notifications for events

Available Events

  • encode.success - WIA Code successfully generated
  • decode.success - WIA Code successfully decoded
  • batch.complete - Batch processing completed
  • quota.warning - 80% of quota used
  • quota.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..."
}

Ready to Start Building?

Join thousands of developers using WIA Code API for precision location services

Frequently Asked Questions

Q: What happens if I exceed my rate limit?

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.

Q: Can I use the API for commercial projects?

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.

Q: How accurate is WIA Code positioning?

All plans provide ±3m accuracy. Enterprise custom plans can achieve ±1m ultra-precision with dedicated infrastructure.

Q: Is it really free for governments?

Yes, all government and public institutions get unlimited free access forever. Simply sign up with a .gov domain email for automatic unlimited plan activation.

Q: Can I white-label the service?

Enterprise Pro plans ($999/month) include white-label options. You can provide the service under your own brand. Contact sales@wiacode.com for details.