TNKB (Tanda Nomor Kendaraan Bermotor) is the official Indonesian vehicle registration system. This project provides comprehensive, production-ready client libraries in Python, JavaScript/TypeScript, and PHP for decoding and validating Indonesian vehicle registration plates.

• Overview
• Features
• Quick Start
• Installation
• Usage Examples
• API Reference
• Supported Regions
• Documentation
• Testing
• Contributing
• License

Indonesian vehicle registration plates follow a standardized format that encodes important information including the vehicle's region of registration. This library provides unified, type-safe interfaces across multiple programming languages to:

• Decode vehicle plate numbers and extract region information
• Validate plate number formats using regex patterns
• Lookup comprehensive region metadata
• Process multiple plates efficiently in batch operations
• Handle network failures gracefully with automatic retries

✅ Plate Decoding - Extract region codes and metadata
✅ Format Validation - Regex-based format checking
✅ Region Lookup - Get detailed region information
✅ Region Listing - Access complete 40+ region mapping
✅ Batch Operations - Check multiple plates efficiently

✅ Automatic Retries - Exponential backoff for network failures
✅ Timeout Protection - Configurable request timeouts
✅ Connection Pooling - Efficient HTTP connection reuse
✅ Fallback Parsing - Work offline with local data
✅ Error Handling - Comprehensive exception types

✅ Type Safety - Full type hints (Python, TypeScript, PHP 7.4+)
✅ Framework Support - Django, Express, Laravel integrations
✅ Code Examples - Working examples for each language
✅ Professional Documentation - Enterprise-grade guides
✅ Unit Tests - Comprehensive test coverage

from tnkb import TNKBClient

client = TNKBClient()
vehicle = client.check_plate('B 1234 ABC')
print(f"Region: {vehicle.region_name}")  # Output: "Jawa Barat"

import { TNKBClient } from 'tnkb-client';

const client = new TNKBClient();
const vehicle = await client.checkPlate('B 1234 ABC');
console.log(`Region: ${vehicle.regionName}`);  // Output: "Jawa Barat"

use TNKB\TNKBClient;

$client = new TNKBClient();
$vehicle = $client->checkPlate('B 1234 ABC');
echo $vehicle->regionName;  // Output: "Jawa Barat"

pip install tnkb-client

Requirements: Python 3.7+, requests library
Dependencies: requests, python-dotenv

npm install tnkb-client

Requirements: Node.js 14+, npm/yarn
Dependencies: axios

composer require nulsec/tnkb-client-php

Requirements: PHP 7.4+, Composer
Dependencies: guzzlehttp/guzzle, vlucas/phpdotenv

Python:

client = TNKBClient()
vehicle = client.check_plate('B 1234 ABC')

print(vehicle.plate_number)    # "B 1234 ABC"
print(vehicle.region_code)     # "B"
print(vehicle.region_name)     # "Jawa Barat"
print(vehicle.vehicle_type)    # "Car"
print(vehicle.is_valid)        # True

TypeScript:

const client = new TNKBClient();
const vehicle = await client.checkPlate('B 1234 ABC');

console.log(vehicle.plateNumber);   // "B 1234 ABC"
console.log(vehicle.regionCode);    // "B"
console.log(vehicle.regionName);    // "Jawa Barat"

PHP:

$client = new TNKBClient();
$vehicle = $client->checkPlate('B 1234 ABC');

echo $vehicle->plateNumber;    // "B 1234 ABC"
echo $vehicle->regionCode;     // "B"
echo $vehicle->regionName;     // "Jawa Barat"

# Check if plate format is valid without making API call
if client.validate_plate('B 1234 ABC'):
    print("Valid format")
else:
    print("Invalid format")

region = client.get_region_info('B')
# Returns: {'code': 'B', 'name': 'Jawa Barat', 'province': 'West Java'}

regions = client.list_regions()
for region in regions:
    print(f"{region['code']}: {region['name']}")
# Output:
# A: DKI Jakarta
# B: Jawa Barat
# C: Jawa Tengah
# ... and 37 more regions

plates = ['B 1234 ABC', 'A 123 DEF', 'AB 5 CDE']
vehicles = client.bulk_check(plates)

for vehicle in vehicles:
    print(f"{vehicle.plate_number} → {vehicle.region_name}")

from tnkb.exceptions import InvalidPlateError, APIError, NetworkError

try:
    vehicle = client.check_plate('INVALID')
except InvalidPlateError as e:
    print(f"Invalid format: {e}")
except APIError as e:
    print(f"API error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")

Decodes a vehicle registration plate and returns region information.

Validates plate number format without making API calls.

Retrieves metadata for a specific region code.

Returns all supported regions (40+ entries).

Efficiently checks multiple plates in batch operation.

VehicleInfo:

plateNumber: string       # e.g., "B 1234 ABC"
regionCode: string        # e.g., "B"
regionName: string        # e.g., "Jawa Barat"
vehicleType: string       # e.g., "Car"
isValid: boolean          # True if valid
details: object           # Additional API response data
createdAt: timestamp      # Creation time

RegionInfo:

code: string              # e.g., "B"
name: string              # e.g., "Jawa Barat"
province: string          # e.g., "West Java"

The library supports 40+ Indonesian provinces and major cities with complete metadata mapping:

See REGION_CODES.md for the complete list.

• README_MAIN.md - Multi-language overview
• DOCUMENTATION_INDEX.md - Complete navigation guide
• FINAL_REPORT.txt - Project delivery report

• README_PYTHON.md - Python implementation guide
• README_TYPESCRIPT.md - JavaScript/TypeScript guide
• README_PHP.md - PHP implementation guide

• CLIENT_LIBRARIES.md - Comprehensive API reference
• PROJECT_SUMMARY.md - Technical details and statistics

• examples/python_basic.py - Python examples
• examples/javascript_basic.js - JavaScript examples
• examples/php_basic.php - PHP examples

Each implementation includes comprehensive unit tests.

python -m pytest tests/ -v
python -m pytest tests/ --cov=tnkb

npm test
npm run test:coverage

composer test
./vendor/bin/phpunit --coverage-html coverage/

All implementations support customizable configuration:

# Python
client = TNKBClient(
    timeout=15,          # seconds
    max_retries=5,
    verify_ssl=True,
    api_key='optional-key'
)

// TypeScript
const client = new TNKBClient({
  timeout: 15000,        // milliseconds
  maxRetries: 5,
  apiKey: 'optional-key',
  baseUrl: 'https://cek-nopol-kendaraan.p.rapidapi.com'
});

// PHP
$config = new ClientConfig(
    timeout: 15,
    maxRetries: 5,
    apiKey: 'optional-key'
);
$client = new TNKBClient($config);

from django.views import View
from tnkb import TNKBClient

class VehicleCheckView(View):
    def __init__(self):
        self.client = TNKBClient()
    
    def post(self, request):
        vehicle = self.client.check_plate(request.POST.get('plate'))
        return JsonResponse(vehicle.to_dict())

const { TNKBClient } = require('tnkb-client');
const client = new TNKBClient();

app.post('/vehicle/check', async (req, res) => {
  try {
    const vehicle = await client.checkPlate(req.body.plate);
    res.json(vehicle);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

Route::post('/vehicle/check', function (Request $request) {
    $client = app(TNKBClient::class);
    $vehicle = $client->checkPlate($request->plate);
    return response()->json($vehicle->toArray());
});

• 23 files created
• 7,200+ lines of code and documentation
• 1,002 lines of core implementation
• 180+ lines of unit tests
• 6,000+ lines of professional documentation
• 40+ region mappings
• 30+ test cases
• 3 language implementations

client = TNKBClient(timeout=30)  # Increase timeout

The library includes automatic retry logic with exponential backoff. Configure max retries:

client = TNKBClient(max_retries=5)

client = TNKBClient(verify_ssl=False)  # Not recommended for production

For detailed troubleshooting, see:

• README_PYTHON.md#troubleshooting
• README_TYPESCRIPT.md#troubleshooting
• README_PHP.md#troubleshooting

• ✅ SSL certificate verification enabled by default
• ✅ Automatic timeout prevention
• ✅ Safe error messages without data leaks
• ✅ Input validation before API calls
• ✅ No sensitive plate logging

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Commit your changes (git commit -m 'feat: Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Documentation: See DOCUMENTATION_INDEX.md
• Issues: GitHub Issues
• Email: [email protected]
• Repository: github.com/nulsec/tnkb-detail

• GraphQL API support
• WebSocket support for real-time checks
• Caching layer (Redis)
• Rate limiting support
• Batch import from CSV
• Web UI for testing

• ✅ Initial release
• ✅ Python, JavaScript/TypeScript, PHP implementations
• ✅ 40+ region mappings
• ✅ Comprehensive error handling
• ✅ Automatic retry logic
• ✅ Complete documentation

This library is maintained by the Security Research Team at NulSec. We thank all contributors and users who help improve this project.

Made with ❤️ by Security Research Team | © 2024 NulSec | Visit Website