TaiGeotrans

CI PyPI version Python 3.11+ License: MIT

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

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

範圍判斷採用近似區域，包含台灣本島、澎湖、金門與馬祖；輸出座標仍固定使用 WGS84（EPSG:4326）與 TWD97（EPSG:3826），不代表行政區界線。

安裝

只使用座標轉換時：

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 8, 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:
Latest release

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 8, 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.1.tar.gz (21.4 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.1-py3-none-any.whl (17.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: taigeotrans-0.1.1.tar.gz
  • Upload date:
  • Size: 21.4 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.1.tar.gz
Algorithm Hash digest
SHA256 cf99d64300ffb5c2eeb48ff757d3c2605baf6643522b8fb24b730c2186152cc4
MD5 5c15a44e894951b7328dc1ea3114f4ba
BLAKE2b-256 c267a483075c037b112310bed0ed6b35b93e04d52c3563097d8d8960876a2758

See more details on using hashes here.

Provenance

The following attestation bundles were made for taigeotrans-0.1.1.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.1-py3-none-any.whl.

File metadata

  • Download URL: taigeotrans-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 17.7 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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f4563c721341d70ea8aaed6efd6e97c7b6301047a28e8faee19d6e5eadf07150
MD5 c59b454c831053cf132ff1ddbc4c4732
BLAKE2b-256 59ffaf596eb00d92aa3a58887569e8a0cc8ed6540c94e12ae81724d8f5f076f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for taigeotrans-0.1.1-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

This release

0.1.1 This release

2 files

0.1.0

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