rtz

A自包含的Rust/JS（通过WASM）地理查找库/二进制/服务器，使用来自自然地球和OpenStreetMap数据集的数据。

免费服务器

服务器部署在全球四个地区，可在tz.twitchax.com访问。每个区域目前可支持约8,000 RPS，部署在以下区域：sea, iad, ams, hkg。

此外，服务器现在将尽力不破坏API版本之间的向后兼容性。这意味着服务器（尝试）不会改变给定API版本的响应格式，并且（尝试）不会从响应中删除任何字段。这并不意味着服务器不会向响应中添加字段，但它（尝试）不会删除它们。

请求形式为 http://tz.twitchax.com/api/v1/osm/tz/{lng}/{lat}。您还可以查看API文档以探索其他端点和版本策略。

示例请求

$ curl http://tz.twitchax.com/api/v1/osm/tz/30/30

[{"id":12,"identifier":"Africa/Cairo","shortIdentifier":"EEST","offset":"UTC+03:00","rawOffset":10800,"rawBaseOffset":7200,"rawDstOffset":3600,"zone":3.0,"currentTime":"2023-07-25T23:39:59.385469400+03:00"}]

HTTPS也可用，但由于客户端和服务器性能开销以及没有传输敏感数据，因此不建议使用。

二进制使用

安装

Windows

$ iwr https://github.com/twitchax/rtz/releases/latest/download/rtz_x86_64-pc-windows-gnu.zip
$ Expand-Archive rtz_x86_64-pc-windows-gnu.zip -DestinationPath C:\Users\%USERNAME%\AppData\Local\Programs\rtz

Mac OS (Apple Silicon)

$ curl -LO https://github.com/twitchax/rtz/releases/latest/download/rtz_aarch64-apple-darwin.zip
$ unzip rtz_aarch64-apple-darwin.zip -d /usr/local/bin
$ chmod a+x /usr/local/bin/rtz

Linux

$ curl -LO https://github.com/twitchax/rtz/releases/latest/download/rtz_x86_64-unknown-linux-gnu.zip
$ unzip rtz_x86_64-unknown-linux-gnu.zip -d /usr/local/bin
$ chmod a+x /usr/local/bin/rtz

Cargo

$ cargo install rtz

NPM

$ npm install --save rtzweb

帮助文档

$ rtz

A tool to easily work with geo lookups via a binary, a library, or a server.

Usage: rtz [COMMAND]

Commands:
  ned           The Natural Earth Data dataset based operations
  osm           The OpenStreetMap dataset based operations
  dump-geojson  Resolve a timezone from a lng,lat pair using the OSM dataset
  serve         Serve the timezone API
  help          Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

解决时区问题

$ rtz ned tz "-87.62,41.88"

Identifier:      America/Chicago
UTC Offset:      UTC-06:00
Offset Seconds:  -21600
Description:     Canada (almost all of Saskatchewan), Costa Rica, El Salvador, Ecuador (Galapagos Islands), Guatemala, Honduras, Mexico (most), Nicaragua,
DST Description: Canada (Manitoba), United States (Illinois, most of Texas)

使用Wasmer运行

wasmer run twitchax/rtz@latest -- ned tz 30,30

运行服务器

$ cargo install rtz --features web
$ rtz serve

$ docker run -it --rm -p 8082 twitchax/rtz

库使用

将其添加到您的 Cargo.toml

[dependencies]
rtz = "*" #choose a version

示例

use rtzlib::NedTimezone;
use rtzlib::CanPerformGeoLookup;

// Query a time zone for a given `(lng,lat)`.
assert_eq!(
    NedTimezone::lookup(-121., 46.)[0]
        .identifier
        .as_ref()
        .unwrap(),
    "America/Los_Angeles"
);

JS使用

npm包可在此处找到。

首先，像任何其他ES模块一样加载模块。

import * as rtz from 'rtzweb/rtzlib.js';

然后，您可以使用该库的方式类似于在Rust中。

let tz = rtz.getTimezoneNed(-121, 46);
tz.identifier; // "America/Los_Angeles"

功能标志

库和二进制都支持各种功能标志。以下是可用的标志

• 顶级
  • default= ["cli"]
  • full= ["tz-ned", "tz-osm", "admin-osm", "自包含"]
• 数据集
  • tz-ned：启用自然地球时区数据集和相关库函数。
  • tz-osm：启用OpenStreetMap时区数据集和相关库函数。
  • admin-osm：启用OpenStreetMap行政数据集和相关库函数。
• 二进制配置
  • cli：启用CLI功能，如果只编译库则可以移除。
  • self-contained：启用自包含功能，将数据集嵌入到二进制文件中构建。
  • double-precision：在所有地方使用f64来表示Geometry和Polygon数据类型，这比f32更准确，但体积更大。
  • unsimplified：生成未简化的数据缓存。需要更多的二进制/内存开销，但更准确。使用原始数据集的细节级别。默认情况是将简化到0.0001的epsilon（通常）。
  • extrasimplified：生成额外的简化数据缓存。需要较少的二进制/内存开销，但准确性较低。这会将简化的epsilon设置为0.01（通常）。
  • owned-decode：在bincode crate的decode功能中使用owned而不是borrow。这通过不直接从二进制映射数据来增加内存占用，但减少了unsafe / 暗黑艺术的使用。
• 特殊修饰符
  • wasm：启用WASM功能，通过wasm-pack构建NPM包或生成wasi二进制文件时是必需的。
  • web = ["full"]：启用serve子命令，该命令启动一个Rocket Web服务器，可以响应时区请求。
• 其他注意事项
  • wasm / wasi构建目前与reqwest和zip不兼容，因此wasm / wasi构建需要启用self-contained功能。

数据更新

最后的更新是在2024.08.08完成的。该日期的数据源如下

• OSM Admin Data。这些数据是从OSM行星文件下载的，然后在本地上处理以提取行政边界。
• OSM TZ Data。这些数据是从时区边界构建程序的最新生成版本中下载的，并由该代码自动处理。
• NED TZ Data。这些数据是从NED矢量存储库的master分支下载的，并由该代码自动处理。

性能

通用

本实现通过使用二进制缓存来提高性能，以换取二进制大小，从而将平均时区解析能力提高约96倍，最坏情况下的解析能力提高约10倍。使用OSM数据集时，平均时区查找时间为大约 930 ns，使用NED数据集时，平均查找时间约为 460 ns。最坏情况下的查找时间约为 6 - 10 μs。

对于随机城市，OSM数据集的查找时间约为 1.5 μs，NED数据集的查找时间约为 400 ns。

免费服务器

以下是使用1,000个并发实现从（lng,lat）对解析到数据中心之一的示例性能，达到8,000 RPS。

以下是使用100个并发从（lng,lat）对解析到数据中心之一的示例性能，平均响应时间约为 24 ms。

测试

cargo test --features web

基准测试

cargo bench --features web

许可证

MIT