Timestamp API

A FastAPI microservice for timezone and city lookup, region bounding, and geospatial queries. This API is a public utility. It may change or be discontinued without notice.

原始信息汇总

Timestamp API 数据集概述

基本信息

• API名称: Timestamp API
• 提供商: augsmachado
• 类别: Location
• 访问平台: RapidAPI
• 定价模型: Freemium
• 免费套餐限制: 每分钟10次请求
• 服务等级: 100%
• 平均延迟: 491ms
• 测试覆盖率: 100%

定价方案

• BASIC: $0.00 / 月
• PRO: $50.00 / 月

API 核心功能

这是一个用于时区和城市查找、区域边界划定和地理空间查询的 FastAPI 微服务。主要功能包括：

• 检查 API 状态和运行时间
• 通过坐标查找时区区域
• 列出所有时区区域及其边界框
• 查找离某个点最近的时区区域或城市
• 按区域、半径、UTC 偏移或夏令时 (DST) 状态列出所有城市
• 查找特定 UTC 偏移下最北、最南、最东和最西的城市

端点详情

1. GET /status

• 描述: 返回 API 状态，包括名称、版本和运行时间（秒）。
• 请求示例: curl --location http://127.0.0.1:8000/status
• 响应示例: 包含 msg, name, version, uptime 字段的 JSON 对象。

2. GET /tz_region

• 描述: 返回包含给定点（纬度，经度）的所有区域。
• 请求示例: curl --location http://127.0.0.1:8000/tz_region?latitude=22.34&longitude=-78.983 --header x-api-key: your_api_key_here
• 响应示例: 包含 regions 数组的 JSON 对象。

3. GET /tz_regions

• 描述: 返回所有区域及其边界框限制。
• 请求示例: curl --location http://127.0.0.1:8000/tz_regions --header x-api-key: your_api_key_here
• 响应示例: 包含 name, min_latitude, max_latitude, min_longitude, max_longitude 字段的 JSON 数组。

4. GET /tz_region_nearest

• 描述: 返回离给定点（纬度，经度）最近的区域。
• 请求示例: curl --location http://127.0.0.1:8000/tz_region_nearest?latitude=38.954&longitude=-12.451 --header x-api-key: your_api_key_here
• 响应示例: 包含 region 和 distance_km 字段的 JSON 对象。

5. GET /tz_region_cities

• 描述: 返回指定区域内的所有城市/时区。
• 请求示例: curl --location http://127.0.0.1:8000/tz_region_cities?region=america --header x-api-key: your_api_key_here
• 响应示例: 包含 region 和 cities 数组的 JSON 对象。城市对象包含 name, latitude, longitude, utc_offset, dst, region 字段。

6. GET /cities_nearest

• 描述: 返回离给定点（纬度，经度）最近的4个城市。
• 请求示例: curl --location http://127.0.0.1:8000/cities_nearest?latitude=40.7128&longitude=-74.0060 --header x-api-key: your_api_key_here
• 响应示例: 包含 tz_location 和 nearest_cities 数组的 JSON 对象。城市对象包含 name, latitude, longitude, distance_km, utc_offset, dst, region 字段。

7. GET /cities_in_radius

• 描述: 返回距离某点给定半径（公里）内的所有城市。
• 请求示例: curl --location http://127.0.0.1:8000/cities_in_radius?latitude=40.7128&longitude=-74.0060&radius_km=750 --header x-api-key: your_api_key_here
• 响应示例: 包含 cities 数组的 JSON 对象。城市对象包含 name, latitude, longitude, utc_offset, dst, region, distance_km 字段。

8. GET /cities_by_utc_offset

• 描述: 返回具有指定 UTC 偏移的所有城市。
• 请求示例: curl --location http://127.0.0.1:8000/cities_by_utc_offset?offset=-5 --header x-api-key: your_api_key_here
• 响应示例: 包含 cities 数组的 JSON 对象。城市对象包含 name, latitude, longitude, utc_offset, dst, region 字段。

9. GET /cities_with_dst

• 描述: 返回当前处于夏令时 (DST) 状态（激活或未激活）的所有城市。
• 请求示例: curl --location http://127.0.0.1:8000/cities_with_dst?dst=true --header x-api-key: your_api_key_here
• 响应示例: 包含 cities 数组的 JSON 对象。城市对象包含 name, latitude, longitude, utc_offset, dst, region 字段。

10. GET /city_extremes

• 描述: 返回给定 UTC 偏移下最北、最南、最东和最西的城市。
• 请求示例: curl --location http://127.0.0.1:8000/city_extremes?offset=0 --header x-api-key: your_api_key_here
• 响应示例: 包含 north, south, east, west 对象的 JSON 对象。每个对象包含 name, latitude, longitude, utc_offset, dst, region 字段。

错误状态码

• 401 Unauthorized: 当 X-API-KEY 请求头缺失或无效时返回（/status 端点除外）。响应体示例：{"detail": "Invalid or missing API Key."}
• 422 Unprocessable Entity: 当必需的查询参数缺失或无效时返回。
• 404 Not Found: 当端点（如 /tz_region_cities 或 /city_extremes）找不到指定的区域或 UTC 偏移时返回。响应体示例：{"error": "Region not found"} 或 {"error": "No cities found for this UTC offset."}

服务声明

此 API 是一个公共实用程序。它可能会在未经通知的情况下更改或停止服务。