전 세계 통합 주소 시스템 - 개발자 문서
Version 2.0 | RESTful API영구 무료
평생 무료
월 100만 건
| 구분 | 일일 한도 | 초당 요청 | 버스트 한도 | 동시 연결 |
|---|---|---|---|---|
| 정부/공공기관 | 무제한 | 무제한 | 무제한 | 무제한 |
| 개인 (무료) | 100 요청 | 1 req/sec | 10 요청 | 1 |
| 기업 스타터 | 10,000 요청 | 10 req/sec | 100 요청 | 10 |
| 기업 프로 ($999) | 1,000,000 요청 | 1,000 req/sec | 10,000 요청 | 1,000 |
| 엔터프라이즈 | 커스텀 | 커스텀 | 커스텀 | 무제한 |
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..."
}
전 세계 수천 명의 개발자들이 WIA Pin Code API로 정밀 위치 서비스를 구축하고 있습니다
429 상태 코드와 함께 Retry-After 헤더가 반환됩니다.
더 높은 한도가 필요하시면 기업 요금제로 업그레이드를 고려해주세요.
네! 개인 무료 요금제도 상업적 사용이 가능합니다. 단, 일일 100회 제한이 있으므로 대량 사용시 기업 요금제를 추천합니다.
모든 요금제에서 ±3m의 높은 정확도를 제공합니다. 엔터프라이즈 요금제는 ±1m의 초정밀 위치 서비스를 제공합니다.
네, 모든 정부 및 공공기관은 영구 무료로 사용 가능합니다. gov 도메인 이메일로 가입하시면 자동으로 무제한 플랜이 적용됩니다.
기업 프로 요금제부터 화이트라벨 옵션을 제공합니다. 자체 브랜드로 서비스를 제공하실 수 있습니다. sales@wiapincode.com로 문의해주세요.