README

PHP SDK for IP138 — IP lookup, mobile attribution, weather queries, and QR code generation

English ｜ 简体中文

While working on multiple projects, I frequently needed to call IP138 APIs. Since there was no official SDK, I had to write HTTP requests, assemble parameters, and handle responses from scratch every time — a lot of repetitive work.

So I wrapped all of IP138's currently available APIs into this PHP SDK. It makes integration much simpler in my own projects, and hopefully helps others with similar needs.

This project has been parsed by Zread — click to view a quick structural overview.

Features

• Covers all IP138 open APIs: IP lookup, mobile attribution, weather queries, and QR code generation
• Supports both global token configuration and per-call token passing — convenient yet flexible
• Four API endpoints available: domestic/global, HTTP/HTTPS
• Response data matches the official IP138 API documentation exactly — no extra learning curve
• Requires PHP >= 8.1

Installation

composer require hejunjie/ip138

Quick Start

Each IP138 API uses a separate token. Two configuration approaches are available:

Option 1: Global Configuration (recommended for calling multiple APIs)

<?php

use Hejunjie\Ip138\IP138;

// Four API endpoints available:
//   IP138::URL_DOMESTIC_HTTP    — Domestic HTTP
//   IP138::URL_DOMESTIC_HTTPS   — Domestic HTTPS
//   IP138::URL_FOREIGN_HTTP     — Global HTTP
//   IP138::URL_FOREIGN_HTTPS    — Global HTTPS

$ip138 = new IP138(IP138::URL_DOMESTIC_HTTPS, [
    'ipdata'  => 'your IP lookup token',
    'mobile'  => 'your mobile attribution token',
    'qrcode'  => 'your QR code token',
    'weather' => 'your weather query token',
]);

// IP lookup
$result = $ip138->ipLookup('47.239.212.111');
print_r($result);

// Mobile attribution
$result = $ip138->mobileLookup('13800138000');

// Weather query
$result = $ip138->weatherLookup(code: '110000', type: 7);

// QR code generation
$path = $ip138->qrcodeLookup('https://example.com', '/save/path');

Option 2: Per-call Token (for simple use cases)

<?php

use Hejunjie\Ip138\IP138;

$result = (new IP138(IP138::URL_DOMESTIC_HTTPS))
    ->ipLookup('47.239.212.111', token: 'your IP lookup token');

print_r($result);

Sample Response

Array
(
    [ret] => ok
    [ip] => 47.239.212.111
    [data] => Array
        (
            [0] => 中国
            [1] => 香港
            [2] => 香港
            [3] =>
            [4] => 阿里云
            [5] => 999077
            [6] => 00852
            [7] => 数据中心
        )
)

API Reference

The token parameter is optional for all methods — if a token was provided in the constructor, it will be used automatically.

Error Handling

All API methods throw Hejunjie\Ip138\Exceptions\IP138Exception when a request fails. It's recommended to catch it in production:

use Hejunjie\Ip138\Exceptions\IP138Exception;

try {
    $result = $ip138->ipLookup('47.239.212.111');
} catch (IP138Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}

Directory Structure

src/
├── IP138.php                  # Entry point — wraps all four API methods
├── Exceptions/
│   └── IP138Exception.php     # Exception class
└── Services/
    ├── BaseService.php        # Base service (HTTP requests, shared logic)
    ├── IpService.php          # IP lookup service
    ├── MobileService.php      # Mobile attribution service
    ├── QrcodeService.php      # QR code generation service
    └── WeatherService.php     # Weather query service

Motivation

The motivation is simple: eliminate repetitive work. IP138's APIs are not complicated on their own, but writing the same request logic across multiple projects is inefficient and hard to maintain. By wrapping them into an SDK, a single update propagates to every project that depends on it.

Contact

Questions or suggestions? Feel free to open an issue on GitHub Issues.