Automatic updates

1. Implementation

The data services provide a version info API for fetching the version info of the latest data. Once a new version is found, you can call the external download API to download the data of the latest version. The core steps are as follows:

Call the version info API to query the version info of the latest data.
Compare the info of the latest version with that of the local version to determine whether the data has been updated.
If there is an update, call the external download API to download the xdb data of the latest version and overwrite the local data to complete the update; if there is no update, wait at least 10 minutes and repeat the 2 steps above.

2. Version detection

After signing in to the community, click Automatic updates under Data services to find your dedicated version info API. The API format looks like this:

// This API URL is not usable; for demonstration only
https://ip2region.net/api/public/data/offline/ver_latest?t=cb0ecb9356.1.6844f7e6.OF001@JCB

Note: request this API at intervals of at least 10 minutes; if the requests are too frequent, the token parameter will be blocked by the system.

Calling this API returns the latest version info of your data service (in JSON format). The data and annotations are as follows:

{
    "errno": 0,         // error code, 0 means success, non-zero means failure
    "errstr": "OK",     // error description, OK when errno is 0, otherwise a specific error description
    "data": {
        "_source": "vinfo",
        "srv_id": "OF001@JCB",                   // id of the current data service
        "model": "v4_monthly",                   // model of the current data service, v4_monthly means monthly update
        "released_at": 1754110800,               // release timestamp of the latest data
        "released_dt": "2025-08-02 13:00:00",    // release date and time of the latest data
        "expired_at": 1875586300,                // expiry timestamp of the current data update service
        "expired_dt": "2029-06-08 12:11:40"      // expiry date and time of the current data update service
    }
}

data.released_at in the response above is the release time of the latest xdb data (note: the hour/minute/second part of this timestamp is forced to 13:00:00 of the release day). To determine whether the local xdb data has been updated, we also need to know the release time of the xdb file in local use.

Search clients such as C/PHP/Golang/Java provide a local API to get the creation timestamp of a given xdb file, for example:

// C
xdb_header_t *header = xdb_load_header(handler);
header->created_at;   // creation timestamp of the xdb file

// PHP
$header = XdbSearcher::loadHeaderFromFile($xdbFile);
$header['createdAt']; // creation timestamp of the xdb file

// Golang
header := xdb.LoadHeaderFromFile(xdbFile);
header.CreatedAt      // creation timestamp of the xdb file

// for other languages, check the source code of the corresponding binding on Github / Gitee

Some search clients do not provide this API. Checking the XDB data structure shows that the header segment of xdb stores the file creation timestamp, and you can obtain it with a few simple file operations. The code logic is as follows:

// open the corresponding xdb file in read-only mode
var handle = fopen("path of the local xdb file", "r");
// move the file pointer to 4
fseek(handle, 4);
// read 4 bytes from the current position
var b4 = fread(handle, 4);
// decode them as a little-endian unsigned integer, which is the creation time of the xdb file
var createdAt = b4[0] | (b4[1] << 8) | (b4[2] << 16) | (b4[3] << 24);

If the createdAt of the local xdb file (converted first as described below) is smaller than the data.released_at returned by the version info API, the local xdb file needs an update. The logic for converting the hour/minute/second part of the xdb file's createdAt is roughly as follows:

// 1, first convert the timestamp into a date, force the time part to 13:00:00, and keep the other parts unchanged
var newDate = date('Y-m-d 13:00:00', xdb.createdAt)
// 2, then convert the resulting newDate into a new timestamp
var timeAt = strtotime(newDate)
// use the resulting timeAt to compare against the released_at returned by the api

Note: it also works to convert both xdb.createdAt and api.released_at to 00:00:00 of the day before comparing. The fastest update cycle is at least one day anyway.

3. Data download

After signing in to the community, click Automatic updates under Data services to find your dedicated external download API. For example, the API of the Full variant XDB of V4 Base looks like this:

This API URL is not usable; for demonstration only
https://ip2region.net/api/public/data/offline/get_file?t=6e94fe429a.1.6842bce6.OF001@JCB&v=v001@full

Note: this API must not be used for update detection. At most 8 requests are allowed per data version; too many requests will get the token blocked by the system.

You can download the Full variant XDB file directly by opening this URL in a download tool or a browser, for example:

// use wget to download the latest xdb file and store it in the local base_full.xdb file
wget https://ip2region.net/api/public/data/offline/get_file?t=6e94fe429a.1.6842bce6.OF001@JCB&v=v001@full -O base_full.xdb

If you download the data with an http client in your code, be sure to enable http redirect following, because the API finally redirects to an Alibaba Cloud oss URL. For example, the core settings when using the curl client are as follows:

var oss_url = "external download API URL";
var ch = curl_init();
curl_setopt(ch, CURLOPT_URL, oss_url);
curl_setopt(ch, CURLOPT_RETURNTRANSFER, 1);      // return the data returned by the API instead of printing it directly
curl_setopt(ch, CURLOPT_TIMEOUT, 1800);          // set the timeout; the xdb file is large and the download may take quite a while
curl_setopt(ch, CURLOPT_FOLLOWLOCATION, true);   // follow the HTTP redirects and access the final oss URL directly

// skip some of the https verification
if (substr(oss_url, 0, 6) == "https:") {
    curl_setopt(ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt(ch, CURLOPT_SSL_VERIFYHOST, false);
}

In practice, whether you cache the whole xdb file in memory or query directly from the file, it is recommended to download the xdb file as follows:

// 1, call the "external download API" to download the latest xdb file into a temporary file; wget is used here for demonstration.
wget https://ip2region.net/api/public/data/offline/get_file?t=6e94fe429a.1.6842bce6.OF001@JCB&v=v001@full -O base_full.tmp.xdb
// 2, move the temporary xdb file onto the production file to complete the upgrade replacement.
// The move operation does not affect file-based query usage.
// If your production uses a full in-memory cache of the whole xdb, reload the new file to replace the xdb instance/reference in use.
move base_full.tmp.xdb base_full.xdb

4. Upgrade script

Based on the upgrade process described above, you can write your own bash script to be run by a scheduled task such as linux crontab, or an upgrade program that sleeps periodically and checks. The rough logic is as follows:

var ver_api_url = "";   // version info API URL
var _dl_api_url = "";   // external download API URL
var _created_at = get_local_xdb_created_at();   // creation time of the local xdb file
// normalize _created_at as described in section 2 of this chapter so it can be compared with api.released_at
var c_createdAt = stdlize_created_at(_created_at);
for ( ; ; ) {
    // 1, call the "version info API" to get the version info of the latest data
    var latest = get_latest_release_info(ver_api_url);
    if (latest.data.released_at <= c_createdAt) {
        // latest release time <= local creation time, no update needed, keep waiting for the next check
        goto wait;
    }

    // 2, call the "external download API" to download the latest xdb file into a temporary file
    var err = download_xdb_to_file(_dl_api_url, "base_full.tmp.xdb");
    if (err != null) {
        // handle the error
        goto wait;
    }

    // 3, move the temporary xdb file onto the production xdb file
    err = move("base_full.tmp.xdb", "base_full.xdb");
    if (err != null) {
        // handle the error
        goto wait;
    }

    // sleep for 10 minutes
    wait:
    sleep(600);
}

The community will later provide an implementation of an automatic upgrade program, open-sourced into the Ip2Region repositories. Stay tuned for further community announcements.