WIA Pin Code API Documentation

Powered by YUJIN Transform

Free tier available • Enterprise solutions • 11cm precision globally

🚀 Introduction

The WIA Pin Code API provides programmatic access to the YUJIN Transform algorithm, converting GPS coordinates to 9-digit universal location codes.

📐 YUJIN Transform
Mathematical foundation: YUJIN(φ,λ) = [⌊((φ+90)/180)×999999⌋]-[⌊((λ+180)/360)×999⌋]
Learn more about YUJIN Transform →

💳 Pricing & Access Levels

Free Tier

FREE
$0
  • ✅ 100 requests/day
  • ✅ Personal use
  • ✅ Basic endpoints
  • ✅ Community support
  • ❌ Batch processing
  • ❌ Commercial use

Enterprise

$999/month
  • ✅ Unlimited requests
  • ✅ Commercial use
  • ✅ All endpoints
  • ✅ Priority support
  • ✅ Batch processing
  • ✅ 99.9% SLA

Government/NGO

FREE
$0
  • ✅ Unlimited requests
  • ✅ Official use
  • ✅ All endpoints
  • ✅ Direct support
  • ✅ Batch processing
  • ✅ Special agreement
⚠️ Commercial Use Policy
Free tier is for personal use only. Any commercial use (delivery services, logistics, real estate, etc.) requires an Enterprise license.

🔑 Authentication

All API requests require an API key. Include it in the request header:

curl -H "X-API-Key: YOUR_API_KEY" \ https://api.wiapincode.com/v1/encode
Header Value Required
X-API-Key Your API key Yes
Content-Type application/json For POST requests

📍 Core Endpoints

GET /v1/encode FREE

Convert GPS coordinates to WIA Pin Code using YUJIN Transform

Parameters:

Parameter Type Description
lat float Latitude (-90 to 90)
lng float Longitude (-180 to 180)

Example Request:

GET /v1/encode?lat=37.5665&lng=126.9780 Response: { "wia_code": "708-698-852", "wia_full": "1-003-708-698-852", "precision_cm": 11, "location": { "latitude": 37.5665, "longitude": 126.9780 } }
GET /v1/decode FREE

Convert WIA Pin Code back to GPS coordinates

Parameters:

Parameter Type Description
wia string WIA Pin Code (e.g., "708-698-852")

Example Request:

GET /v1/decode?wia=708-698-852 Response: { "latitude": 37.5665, "longitude": 126.9780, "wia_code": "708-698-852", "city": "Seoul", "country": "South Korea" }
POST /v1/validate FREE

Validate WIA Pin Code format and checksum

POST /v1/validate { "wia_code": "708-698-852" } Response: { "valid": true, "format": "XXX-XXX-XXX", "type": "standard", "precision_cm": 11 }
GET /v1/distance FREE

Calculate distance between two WIA Pin Codes

GET /v1/distance?from=708-698-852&to=716-005-285 Response: { "distance_km": 11087.54, "distance_miles": 6889.23, "bearing": 34.5, "travel_time_estimate": { "flight": "13 hours", "driving": "Not possible" } }
POST /v1/batch/encode

Batch convert up to 10,000 GPS coordinates

POST /v1/batch/encode { "locations": [ {"lat": 37.5665, "lng": 126.9780, "id": "seoul"}, {"lat": 35.6762, "lng": 139.6503, "id": "tokyo"}, // ... up to 10,000 items ] } Response: { "results": [ {"id": "seoul", "wia_code": "708-698-852"}, {"id": "tokyo", "wia_code": "698-167-888"}, ], "processed": 2, "errors": 0 }
POST /v1/enterprise/phone-link

Link phone numbers to WIA Pin Codes for delivery services

POST /v1/enterprise/phone-link { "phone": "+82-10-1234-5678", "wia_code": "708-698-852", "type": "primary", "schedule": { "weekday": "708-698-852", // Office "weekend": "709-123-456" // Home } }

⚡ Rate Limits

Tier Requests/Day Requests/Second Batch Size
Free 100 1 N/A
Enterprise Unlimited 100 10,000
Government/NGO Unlimited 50 10,000
📊 Rate Limit Headers
Every response includes rate limit information:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Time when limit resets (Unix timestamp)

❌ Error Codes

Code Message Description
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Missing or invalid API key
403 Forbidden Access denied (e.g., free tier accessing enterprise endpoint)
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error (rare)

📦 SDKs & Libraries

JavaScript/Node.js

// Install npm install wia-pincode-sdk // Usage const WIA = require('wia-pincode-sdk'); const wia = new WIA('YOUR_API_KEY'); // Encode GPS to WIA const result = await wia.encode(37.5665, 126.9780); console.log(result.wia_code); // "708-698-852" // Decode WIA to GPS const location = await wia.decode('708-698-852'); console.log(location.latitude, location.longitude);

Python

# Install pip install wia-pincode-sdk # Usage from wia_code import WIAClient client = WIAClient('YOUR_API_KEY') # Encode GPS to WIA result = client.encode(37.5665, 126.9780) print(result['wia_code']) # "708-698-852" # Decode WIA to GPS location = client.decode('708-698-852') print(location['latitude'], location['longitude'])

PHP

// Install via Composer composer require wia-code/sdk // Usage $wia = new WIACode\Client('YOUR_API_KEY'); // Encode GPS to WIA $result = $wia->encode(37.5665, 126.9780); echo $result->wia_code; // "708-698-852" // Decode WIA to GPS $location = $wia->decode('708-698-852'); echo $location->latitude . ', ' . $location->longitude;

🚀 Implementation Guide

For Delivery Services

// 1. Customer provides phone number const phoneNumber = '+82-10-1234-5678'; // 2. Get WIA Pin Code linked to phone const { wia_code } = await wia.getLocationByPhone(phoneNumber); // 3. Navigate to location const { latitude, longitude } = await wia.decode(wia_code); navigateTo(latitude, longitude);

For Emergency Services

// 1. Get caller's WIA Pin Code const wiaCode = '708-698-852'; // 2. Find nearest emergency units const units = await wia.findNearestEmergency(wiaCode, { type: 'ambulance', radius: 10 // km }); // 3. Dispatch to exact location dispatch(units[0], wiaCode);

❓ FAQ

What is YUJIN Transform?

YUJIN Transform is the mathematical formula that powers WIA Pin Code, converting GPS coordinates to 9-digit codes. Learn more →

Can I use the free API for my business?

No, commercial use requires an Enterprise license ($999/month). The free tier is for personal use, education, and testing only.

How accurate is WIA Pin Code?

WIA Pin Code provides 11cm precision at the equator, with even better precision at higher latitudes. This is more accurate than most GPS devices.

Is the API available in my country?

Yes! WIA Pin Code works globally. Government and NGO usage is free in 50+ developing nations.

🤝 Ready to Get Started?

Join thousands of developers using WIA Pin Code API

Get Free API Key Contact Sales

Questions? Email us at api@wiapincode.com