TaiGeotrans

CI PyPI version Python 3.11+ License: MIT

TaiGeotrans 是一個台灣地址與座標轉換工具，支援：

  • WGS84（EPSG:4326）與 TWD97（EPSG:3826）雙向轉換
  • 透過 TGOS 將台灣地址轉成座標
  • 批量處理、pandas DataFrame 與 GeoJSON
  • 命令列操作

安裝

只使用座標轉換時：

python -m pip install taigeotrans

需要地址定位、DataFrame 或 CLI 時，再安裝對應功能：

python -m pip install "taigeotrans[geocoding]"
python -m pip install "taigeotrans[dataframe]"
python -m pip install "taigeotrans[cli]"

也可以一次安裝全部功能：

python -m pip install "taigeotrans[all]"

Python API

from taigeotrans import TaiGeotrans

tg = TaiGeotrans()

# WGS84 -> TWD97
result = tg.transform_lonlat(121.5654, 25.0330)
print(result.twd97_x, result.twd97_y)

# TWD97 -> WGS84
result = tg.transform_twd97(303891.54, 2773226.67)
print(result.wgs84_lon, result.wgs84_lat)

地址定位

地址定位使用 TGOS，需要 AppID 與 APIKey。請先在 TGOS 申請這兩項資料， 再透過環境變數提供：

export TGOS_APP_ID="your-app-id"
export TGOS_API_KEY="your-api-key"

或直接傳給 TaiGeotrans：

tg = TaiGeotrans(
    tgos_app_id="your-app-id",
    tgos_api_key="your-api-key",
)
result = tg.geocode("臺北市中山區松江路469巷4號")
print(result.matched_address, result.twd97_x, result.twd97_y)

Python API 不會自動讀取 .env。CLI 會讀取目前工作目錄的 .env，可以複製 .env.example 作為範本；實際 key 不要提交到 Git。

批量處理

addresses = ["嘉義縣民雄鄉中樂路55號", "臺北市信義區市府路1號"]
coords = [(120.4278, 23.5521), (121.5654, 25.0330)]

address_results = tg.batch_geocode(addresses, show_progress=False)
coordinate_results = tg.batch_transform_lonlat(coords, show_progress=False)
df = tg.batch_transform_lonlat_to_dataframe(coords, show_progress=False)

DataFrame 方法需要 taigeotrans[dataframe]。進度列使用 tqdm；沒有安裝時， 批量方法仍可執行，只是不顯示進度列。

CLI

python -m pip install "taigeotrans[cli]"

taigeotrans transform 121.5654 25.0330
taigeotrans transform 121.5654 25.0330 --format json
taigeotrans geocode "臺北市信義區市府路1號"
taigeotrans batch-geocode addresses.txt -o results.csv
taigeotrans batch-transform coords.csv -o results.csv

addresses.txt 每行一個地址；coords.csv 需要包含 lon,lat 欄位。執行 taigeotrans --help 查看完整指令。

結果

每個操作都回傳 GeocodeResult，包含輸入值、WGS84/TWD97 座標、來源與狀態。 狀態可能是 success、out_of_bounds、invalid 或 failed。

開發

python -m pip install -e ".[dev,all]"
python -m pytest
python -m ruff check src tests
python -m ruff format --check src tests
python -m mypy src
python -m build
python -m twine check dist/*

CI 會測試 Python 3.11–3.13。推送 vMAJOR.MINOR.PATCH tag 後，release workflow 會建置套件、發佈到 PyPI，並建立 GitHub Release。

授權

MIT License，請參考 LICENSE。

Project links

Data verified by PyPI on Aug 7, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for KageRyo from gravatar.com KageRyo

Credits

Author: TaiGeotrans Contributors

GitHub Statistics

Data verified by PyPI on Aug 7, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

geocoding dataframe progress cli all dev

Tags

taiwan geospatial coordinate transform TWD97 WGS84 geocoding

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

taigeotrans-0.1.0.tar.gz (18.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

taigeotrans-0.1.0-py3-none-any.whl (16.9 kB view details)

Uploaded Python 3

File details

Details for the file taigeotrans-0.1.0.tar.gz.

File metadata

  • Download URL: taigeotrans-0.1.0.tar.gz
  • Upload date:
  • Size: 18.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for taigeotrans-0.1.0.tar.gz
Algorithm Hash digest
SHA256 d614863e5baf17f0b0a17cd2576c55dd9c86ccd3b789a044677b9692096a96c2
MD5 50d4011ee62e09c4384ad1489fe701d0
BLAKE2b-256 52d4508cb1ee8f4516085a515fb8d91bbeb9490621cfff23b30e6fbe09b34227

See more details on using hashes here.

Provenance

The following attestation bundles were made for taigeotrans-0.1.0.tar.gz:

Publisher: release.yml on KageRyo/TaiGeotrans

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file taigeotrans-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: taigeotrans-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 16.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for taigeotrans-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1b52bc2a9c20050e749cf7b14cbdd5c8ad6e42d28d657f238c76242773a0881b
MD5 249a8817f82cc4df75854302ac94e248
BLAKE2b-256 f32cf749eb479d2d1aa08870a86892621f08953fc7092a92e15250ea3cf51699

See more details on using hashes here.

Provenance

The following attestation bundles were made for taigeotrans-0.1.0-py3-none-any.whl:

Publisher: release.yml on KageRyo/TaiGeotrans

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.1

2 files

This release

0.1.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page