WIA Pin Code API Documentation - YUJIN Transform Implementation

🚀 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 Plans — Individuals, Non-Profits & Governments

Free

FREE

$0

Individuals · Developers

✅ 100 requests/day
✅ 211 languages
✅ 9-digit codes
✅ Community support
❌ Commercial use

Get Free API Key

NGO / Non-Profit

FREE

$0

Humanitarian · Aid Organizations

✅ Unlimited requests
✅ 211 languages
✅ 9 + 12-digit codes
✅ Batch + Grid generation
✅ Priority support

Apply for Access

Government

FREE

$0

Nations · Public Sector

✅ Unlimited requests
✅ 211 languages
✅ National deployment
✅ Grid generation
✅ Direct technical support

Apply for Access

💼 Business Plans — Commercial API Access

Starter

$99/month

Startups · Small Business

✅ 10,000 requests/day
✅ 211 languages
✅ 9 + 12-digit codes
✅ Commercial use
✅ CSV batch (1K)

Subscribe $99/mo

Business ⭐

POPULAR

$499/month

Mid-size · Logistics · Delivery

✅ 100,000 requests/day
✅ 211 languages
✅ 9 + 12-digit codes
✅ Priority support
✅ CSV batch (100K)
✅ 99.9% SLA

Subscribe $499/mo

Enterprise

$999/month

Corporations · National Scale

✅ Unlimited requests
✅ 211 languages
✅ 9 + 12-digit codes
✅ 24/7 dedicated support
✅ Unlimited batch
✅ Dedicated server
✅ 99.99% SLA

Subscribe $999/mo

⚠️ Commercial Use Policy
Free tier is for personal use only. Any commercial use (delivery services, logistics, real estate, etc.) requires a paid plan.

🔑 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.smilestory.ai/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 ENTERPRISE

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 ENTERPRISE

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
Starter ($99)	10,000	10	1,000
Business ($499)	100,000	50	100,000
Enterprise ($999)	Unlimited	100	Unlimited
Government/NGO	Unlimited	50	Unlimited

📊 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 a paid plan (Starter $99, Business $499, or Enterprise $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 wiasoom@smilestory.ai