WIA Pin Code API

전 세계 통합 주소 시스템 - 개발자 문서

Version 2.0 | RESTful API

📊 API 요금제 & 한도

🏛️ 정부/공공기관
무료

영구 무료

  • ✓ 전체 시스템 무료
  • ✓ 무제한 WIA Pin Code 생성
  • ✓ 기술 지원 포함
  • ✓ 교육 자료 제공
  • ✓ API 무제한 사용
  • ✓ 커스텀 통합 지원
🏢 기업 API
$999

월 100만 건

  • ✓ 대량 처리 API
  • ✓ 99.9% SLA 보장
  • ✓ 전담 지원팀
  • ✓ 커스텀 통합
  • ✓ 분석 대시보드
  • ✓ 화이트라벨 옵션
구분 일일 한도 초당 요청 버스트 한도 동시 연결
정부/공공기관 무제한 무제한 무제한 무제한
개인 (무료) 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
엔터프라이즈 커스텀 커스텀 커스텀 무제한

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 wiapincode.com/signup
  2. Verify your email address
  3. Navigate to Dashboard → API Keys
  4. Click "Generate New Key"

API Endpoints

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

Convert latitude/longitude coordinates to WIA Pin 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.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"
  }'

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://wiapincode.com/map/852-623-518-816"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-08-22T10:30:00Z",
    "api_version": "2.0"
  }
}
GET https://api.wiapincode.com/v2/decode/{wia_code}

Convert WIA Pin Code back to coordinates and location details

Path Parameters

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"

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.wiapincode.com/v2/batch BETA

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

Find nearby locations with WIA Pin Codes

Query Parameters

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

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"

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.wiapincode.com/v2/distance

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

Code Examples

JavaScript (Node.js)

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

Python

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

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

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 Pin 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 wiapincode
🐘

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 Pin Code successfully generated
  • decode.success - WIA Pin 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..."
}

지금 바로 시작하세요!

전 세계 수천 명의 개발자들이 WIA Pin Code API로 정밀 위치 서비스를 구축하고 있습니다

자주 묻는 질문 (FAQ)

Q: 일일 한도를 초과하면 어떻게 되나요?

429 상태 코드와 함께 Retry-After 헤더가 반환됩니다. 더 높은 한도가 필요하시면 기업 요금제로 업그레이드를 고려해주세요.

Q: 상업적 프로젝트에 사용할 수 있나요?

네! 개인 무료 요금제도 상업적 사용이 가능합니다. 단, 일일 100회 제한이 있으므로 대량 사용시 기업 요금제를 추천합니다.

Q: WIA Pin Code의 정확도는 어느 정도인가요?

모든 요금제에서 ±3m의 높은 정확도를 제공합니다. 엔터프라이즈 요금제는 ±1m의 초정밀 위치 서비스를 제공합니다.

Q: 정부 기관은 정말 무료인가요?

네, 모든 정부 및 공공기관은 영구 무료로 사용 가능합니다. gov 도메인 이메일로 가입하시면 자동으로 무제한 플랜이 적용됩니다.

Q: 화이트라벨 서비스를 제공하나요?

기업 프로 요금제부터 화이트라벨 옵션을 제공합니다. 자체 브랜드로 서비스를 제공하실 수 있습니다. sales@wiapincode.com로 문의해주세요.