amap-python-sdk

English | 简体中文

Overview

This repository is a Python client for the Amap (Gaode) Web Service APIs. It provides a synchronous client and a matching asynchronous client for applications built around asyncio.

See the "Available APIs" section below for a table of the Web APIs wrapped by this SDK.

Installation

pip install amap-python-sdk

The PyPI distribution is named amap-python-sdk; the Python import package remains amap. The package supports Python 3.10 and later, and installs its HTTP dependencies (requests and aiohttp) automatically.

API key

Create a Web Service API key in the Amap developer console.

Synchronous usage

The synchronous client is the recommended starting point. Methods return the parsed Amap JSON response as a dictionary.

import os

from amap import Amap

amap = Amap(os.environ["AMAP_API_KEY"])
try:
    # POI keyword search
    pois = amap.place.text(
        "coffee",
        region="上海",
        city_limit=True,
        page_size=10,
        page_num=1,
    )

    # Nearby search; coordinates are (longitude, latitude)
    nearby = amap.place.around(
        "coffee",
        location=("121.4737", "31.2304"),
        radius=1500,
    )

    # Search within a closed polygon (first and last points match)
    in_area = amap.place.polygon(
        ("116.4074", "39.9042"),
        ("116.4200", "39.9042"),
        ("116.4200", "39.9150"),
        ("116.4074", "39.9042"),
        keywords="museum",
    )

    # Retrieve a POI by its Amap ID
    poi = amap.place.detail("YOUR_POI_ID")

    # Other services
    weather = amap.weather.info("110000")
    districts = amap.district.list("北京市")
    geocode = amap.georegeo.geo("北京市朝阳区阜通东大街6号")
    reverse_geocode = amap.georegeo.regeo(("116.481488", "39.990464"))
    route = amap.direction.driving(
        ("116.481028", "39.989643"),
        ("116.434446", "39.90816"),
    )
finally:
    amap.close()

Coordinates are provided as (longitude, latitude). The methods accept endpoint-specific keyword arguments; refer to their docstrings and the corresponding Amap API documentation for the full parameter list.

Asynchronous usage

amap.aio.Amap provides the corresponding asyncio client, implemented with aiohttp. Its service methods mirror the synchronous client.

import asyncio
import os

from amap.aio import Amap


async def main():
    async with Amap(os.environ["AMAP_API_KEY"]) as amap:
        result = await amap.place.text("coffee", region="上海")
        print(result)


asyncio.run(main())

Available APIs

The SDK wraps the following Amap Web APIs:

Service availability, required permissions, and API limits should be checked in the official Amap documentation.

Errors

If Amap returns a JSON response with "status": "0", the client raises amap.exceptions.AmapAPIError. The exception exposes the original response, info, and infocode:

from amap.exceptions import AmapAPIError

try:
    result = amap.place.text("coffee")
except AmapAPIError as exc:
    print(exc.infocode, exc.info)
    print(exc.response)

The SDK preserves Amap's infocode instead of guessing its meaning from a numeric prefix. Check the official Amap error-code reference and the documentation for the specific API. When the underlying HTTP library reports a request timeout, the client raises amap.exceptions.AmpTimeoutError; other network and HTTP transport errors are raised by requests or aiohttp.

Requirements

• Python >=3.10,<4.0
• requests for the synchronous client
• aiohttp for the asynchronous client

Exact dependency constraints are maintained in pyproject.toml.

Contributing

Contributions are welcome. If submitting changes, please include unit tests for any behavior changes or new features.

Run the test suite with:

uv run pytest

License

MIT