欢迎使用 GeoPy 文档！

GeoPy logo
文档

https://geopy.pythonlang.cn/

源代码

https://github.com/geopy/geopy

Stack Overflow

https://stackoverflow.com/questions/tagged/geopy

GIS Stack Exchange

https://gis.stackexchange.com/questions/tagged/geopy

讨论

https://github.com/geopy/geopy/discussions

问题跟踪器

https://github.com/geopy/geopy/issues

PyPI

https://pypi.ac.cn/project/geopy/

geopy 是一个 Python 客户端，用于多个流行的地理编码 Web 服务。

geopy 使 Python 开发人员能够轻松地使用第三方地理编码器和其他数据源来查找全球地址、城市、国家和地标的坐标。

geopy 已在 CPython (版本 3.7、3.8、3.9、3.10、3.11、3.12) 和 PyPy3 上进行了测试。geopy 1.x 系列还支持 CPython 2.7、3.4 和 PyPy2。

目录

安装

pip install geopy

地理编码器

您可能使用的每个地理定位服务（如 Google Maps、Bing Maps 或 Nominatim）在 geopy.geocoders 中都有自己的类，用于抽象该服务的 API。地理编码器都至少定义了一个 geocode 方法，用于从字符串解析位置，并且可能定义了一个 reverse 方法，用于将坐标对解析为地址。每个地理编码器在初始化时都接受与服务交互所需的任何凭据或设置，例如 API 密钥或语言环境。

将查询地理定位到地址和坐标

>>> from geopy.geocoders import Nominatim
>>> geolocator = Nominatim(user_agent="specify_your_app_name_here")
>>> location = geolocator.geocode("175 5th Avenue NYC")
>>> print(location.address)
Flatiron Building, 175, 5th Avenue, Flatiron, New York, NYC, New York, ...
>>> print((location.latitude, location.longitude))
(40.7410861, -73.9896297241625)
>>> print(location.raw)
{'place_id': '9167009604', 'type': 'attraction', ...}

查找与一组坐标相对应的地址

>>> from geopy.geocoders import Nominatim
>>> geolocator = Nominatim(user_agent="specify_your_app_name_here")
>>> location = geolocator.reverse("52.509669, 13.376294")
>>> print(location.address)
Potsdamer Platz, Mitte, Berlin, 10117, Deutschland, European Union
>>> print((location.latitude, location.longitude))
(52.5094982, 13.3765983)
>>> print(location.raw)
{'place_id': '654513', 'osm_type': 'node', ...}

定位器的 geocode 和 reverse 方法需要参数 query，并且至少还接受参数 exactly_one，默认值为 True。地理编码器可能具有其他属性，例如，Bing 接受 user_location，其作用是偏向该位置附近的結果。 geocode 和 reverse 方法可能返回三种类型的值

  • 当没有找到結果时，返回 None。

  • 当方法的 exactly_one 参数为 True 且至少找到一个結果时，返回一个 geopy.location.Location 对象，该对象可以像这样进行迭代

    (address<String>, (latitude<Float>, longitude<Float>))

    也可以访问 location.address、location.latitude、location.longitude、location.altitude 和 location.raw。最后一条包含此結果的完整地理编码器响应。

  • 当 exactly_one 为 False 且至少找到一个結果时，返回一个 geopy.location.Location 对象列表，如上所述

    [location, [...]]

如果服务不可用或以其他方式返回非 OK 响应，或者未在分配的时间范围内收到响应，您将收到以下详细介绍的 异常 之一。

一次性指定参数

地理编码方法接受许多不同的参数，您可能希望只指定其中一些参数，以后就不再关心它们。

使用 Python 的 functools.partial() 很容易做到这一点

>>> from functools import partial
>>> from geopy.geocoders import Nominatim

>>> geolocator = Nominatim(user_agent="specify_your_app_name_here")

>>> geocode = partial(geolocator.geocode, language="es")
>>> print(geocode("london"))
Londres, Greater London, Inglaterra, SW1A 2DX, Gran Bretaña
>>> print(geocode("paris"))
París, Isla de Francia, Francia metropolitana, Francia
>>> print(geocode("paris", language="en"))
Paris, Ile-de-France, Metropolitan France, France

>>> reverse = partial(geolocator.reverse, language="es")
>>> print(reverse("52.509669, 13.376294"))
Steinecke, Potsdamer Platz, Tiergarten, Mitte, 10785, Alemania

如果您需要修改查询，也可以使用带有 lambda 的单行代码。例如，如果您只需要对 克利夫兰，俄亥俄州 中的位置进行地理编码，您可以执行以下操作

>>> geocode = lambda query: geolocator.geocode("%s, Cleveland OH" % query)
>>> print(geocode("11111 Euclid Ave"))
Thwing Center, Euclid Avenue, Magnolia-Wade Park Historic District,
University Circle, Cleveland, Cuyahoga County, Ohio, 44106, United States
of America

该 lambda 不接受关键字参数。如果您需要关键字参数，可以执行以下操作

>>> _geocode = partial(geolocator.geocode, language="es")
>>> geocode = lambda query, **kw: _geocode("%s, Cleveland OH" % query, **kw)
>>> print(geocode("11111 Euclid Ave"))
Thwing Center, Euclid Avenue, Magnolia-Wade Park Historic District,
University Circle, Cleveland, Cuyahoga County, Ohio, 44106, Estados Unidos
>>> print(geocode("11111 Euclid Ave", language="en"))
Thwing Center, Euclid Avenue, Magnolia-Wade Park Historic District,
University Circle, Cleveland, Cuyahoga County, Ohio, 44106, United States
of America

GeoPy 不是服务

地理编码由许多不同的服务提供，这些服务与 geopy 没有任何关联。这些服务提供 API，任何人都可以实现，而 geopy 只是一个库，它在一个包中为许多不同的服务提供了这些实现。

_images/geopy_and_geocoding_services.svg

因此

  1. 不同的服务具有不同的使用条款、配额、定价、地理数据库等等。例如，Nominatim 是免费的，但提供了低请求限制。如果您需要发出更多查询，请考虑使用其他（可能是付费的）服务，例如 OpenMapQuest 或 PickPoint（这两个是 Nominatim 的商业提供商，因此它们应该具有相同的数据和 API）。或者，如果您愿意等待，可以尝试 geopy.extra.rate_limiter。

  2. geopy 无法对地理编码服务的数据库负责。如果您遇到某些服务无法满足的查询问题，应将其转交给该服务的支持团队。

  3. geopy 无法对您计算机与地理编码服务之间的任何网络问题负责。

如果您遇到当前地理编码服务提供商的任何问题，您可以随时尝试其他提供商。

异步模式

默认情况下，geopy 地理编码器是同步的（即它们使用基于 BaseSyncAdapter 的适配器）。

所有地理编码器都可以通过简单地切换到基于 BaseAsyncAdapter 的适配器（如 AioHTTPAdapter）与 asyncio 一起使用。

示例

from geopy.adapters import AioHTTPAdapter
from geopy.geocoders import Nominatim

async with Nominatim(
    user_agent="specify_your_app_name_here",
    adapter_factory=AioHTTPAdapter,
) as geolocator:
    location = await geolocator.geocode("175 5th Avenue NYC")
    print(location.address)

基本上用法与同步模式相同，只是所有地理编码器调用都应使用 await，并且地理编码器实例应通过 async with 创建。上下文管理器是可选的，但是强烈建议使用它以避免资源泄漏。

访问地理编码器

检索地理编码器类的典型方法是从 geopy.geocoders 包中进行导入

from geopy.geocoders import Nominatim
geopy.geocoders.get_geocoder_for_service(service)

对于提供的服务，尝试返回地理编码器类。

>>> from geopy.geocoders import get_geocoder_for_service
>>> get_geocoder_for_service("nominatim")
geopy.geocoders.nominatim.Nominatim

如果给定的字符串无法识别，则会引发 geopy.exc.GeocoderNotFound 异常。

鉴于几乎所有地理编码器都提供 geocode 方法，因此可以使用它基于用户输入完全进行基本查询

from geopy.geocoders import get_geocoder_for_service

def geocode(geocoder, config, query):
    cls = get_geocoder_for_service(geocoder)
    geolocator = cls(**config)
    location = geolocator.geocode(query)
    return location.address

>>> geocode("nominatim", dict(user_agent="specify_your_app_name_here"), "london")
'London, Greater London, England, SW1A 2DX, United Kingdom'
>>> geocode("photon", dict(), "london")
'London, SW1A 2DX, London, England, United Kingdom'

默认选项对象

class geopy.geocoders.options

options 对象包含地理编码器的默认配置值，例如 timeout 和 User-Agent。与其分别将自定义值传递给每个地理编码器，不如覆盖此对象中的默认值。

请注意，并非所有地理编码器都使用该对象的全部属性。例如，一些地理编码器不尊重 default_scheme 属性。请参阅特定地理编码器的初始化程序文档，了解该地理编码器接受的参数列表。

覆盖默认 timeout 和 user_agent 的示例

>>> import geopy.geocoders
>>> from geopy.geocoders import Nominatim
>>> geopy.geocoders.options.default_user_agent = 'my_app/1'
>>> geopy.geocoders.options.default_timeout = 7
>>> geolocator = Nominatim()
>>> print(geolocator.headers)
{'User-Agent': 'my_app/1'}
>>> print(geolocator.timeout)
7
属性
default_adapter_factory

一个可调用函数，返回 geopy.adapters.BaseAdapter 实例。适配器是 HTTP 客户端的不同实现。有关更多信息，请参阅 geopy.adapters。

此可调用函数接受两个关键字参数：proxies 和 ssl_context。类也可以指定为此可调用函数。

示例

import geopy.geocoders
geopy.geocoders.options.default_adapter_factory = geopy.adapters.URLLibAdapter

geopy.geocoders.options.default_adapter_factory = (
    lambda proxies, ssl_context: MyAdapter(
        proxies=proxies, ssl_context=ssl_context, my_custom_arg=42
    )
)

如果安装了 requests 包，则默认适配器为 geopy.adapters.RequestsAdapter。否则，它为 geopy.adapters.URLLibAdapter。

版本 2.0 中的新增功能。

default_proxies

通过 HTTP 代理隧道请求。

默认情况下，系统代理将被尊重（例如，HTTP_PROXY 和 HTTPS_PROXY 环境变量或特定于平台的代理设置，例如 macOS 或 Windows 本机首选项 - 有关更多详细信息，请参阅 urllib.request.getproxies()）。使用系统代理的 proxies 值为 None。

要禁用系统代理并直接发出请求，请显式地传递一个空字典作为 proxies 的值：{}。

要使用自定义 HTTP 代理位置，请传递一个字符串。有效示例为

  • "192.0.2.0:8080"

  • "john:passw0rd@192.0.2.0:8080"

  • "http://john:passw0rd@192.0.2.0:8080"

请注意

  • 代理的方案部分（http://）将被忽略。

  • 只支持 http 代理。即使代理方案是 https，它也会被忽略，并且客户端和代理之间的连接仍然是不加密的。但是，仍然支持通过 http 代理的 https 请求（通过 HTTP CONNECT 方法）。

可以提供原始的 urllib 样式 proxies 字典，而不是字符串

  • {"https": "192.0.2.0:8080"} - 意味着 HTTP 代理仅用于具有 https 方案的请求。字符串 proxies 值会自动用于两种方案，并且作为 urllib 样式 proxies 字典的简写提供。

有关更多信息，请参阅有关 urllib.request.getproxies() 的文档。

default_scheme

使用 'https' 或 'http' 作为 API URL 的方案。

default_ssl_context

具有自定义 TLS 验证设置的 ssl.SSLContext 实例。传递 None 以使用解释器的默认值（即使用系统的可信 CA 证书）。

要使用 requests 库使用的 CA 捆绑包

import ssl
import certifi
import geopy.geocoders
ctx = ssl.create_default_context(cafile=certifi.where())
geopy.geocoders.options.default_ssl_context = ctx

要完全禁用 TLS 证书验证

import ssl
import geopy.geocoders
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE
geopy.geocoders.options.default_ssl_context = ctx

有关更多示例，请参阅 ssl.SSLContext 类的文档。

default_timeout

以秒为单位的时间，等待地理编码服务响应，然后再引发 geopy.exc.GeocoderTimedOut 异常。传递 None 以禁用超时。

default_user_agent

与地理编码器 API 请求一起发送的用户代理标头。

default_adapter_factory

geopy.adapters.RequestsAdapter 的别名

default_proxies = None
default_scheme = 'https'
default_ssl_context = None
default_timeout = 1
default_user_agent = 'geopy/2.4.1'

与 Pandas 一起使用

可以使用 geopy 对 pandas DataFrame 进行地理编码，但是必须考虑速率限制。

大量 DataFrame 行可能会产生大量的地理编码请求到地理编码服务，这可能会被该服务限制（例如，通过返回 Too Many Requests 429 HTTP 错误或超时）。

geopy.extra.rate_limiter 类提供了一个便捷的包装器，可用于自动在地理编码调用之间添加延迟，以减少对地理编码服务的负载。它还可以重试失败的请求并吞并单个行的错误。

如果您遇到 Too Many Requests 错误，您可以尝试以下方法

  • 使用 geopy.extra.rate_limiter 和非零 min_delay_seconds。

  • 尝试不同的地理编码服务（请先咨询他们的 ToS，因为某些服务禁止批量地理编码）。

  • 在所选的地理编码服务上获取付费计划，该计划提供更高的配额。

  • 配置您自己的地理编码服务的本地副本（例如 Nominatim）。

速率限制器

RateLimiter 和 AsyncRateLimiter 允许执行批量操作，同时优雅地处理错误响应并在需要时添加延迟。

在下面的示例中，将在每个 geolocator.geocode 调用对之间添加 1 秒（min_delay_seconds=1）的延迟；所有 geopy.exc.GeocoderServiceError 异常将被重试（最多 max_retries 次）

import pandas as pd
df = pd.DataFrame({'name': ['paris', 'berlin', 'london']})

from geopy.geocoders import Nominatim
geolocator = Nominatim(user_agent="specify_your_app_name_here")

from geopy.extra.rate_limiter import RateLimiter
geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1)
df['location'] = df['name'].apply(geocode)

df['point'] = df['location'].apply(lambda loc: tuple(loc.point) if loc else None)

这将生成以下 DataFrame

>>> df
     name                                           location  \
0   paris  (Paris, Île-de-France, France métropolitaine, ...
1  berlin  (Berlin, 10117, Deutschland, (52.5170365, 13.3...
2  london  (London, Greater London, England, SW1A 2DU, UK...

                           point
0   (48.8566101, 2.3514992, 0.0)
1  (52.5170365, 13.3888599, 0.0)
2  (51.5073219, -0.1276474, 0.0)

要将额外选项传递给 geocode 调用

from functools import partial
df['location'] = df['name'].apply(partial(geocode, language='de'))

要查看进度条

from tqdm import tqdm
tqdm.pandas()
df['location'] = df['name'].progress_apply(geocode)

在使用速率限制类之前，请咨询地理编码服务的 ToS，该服务可能明确地将批量请求（即使是受限制的）视为违规行为。

class geopy.extra.rate_limiter.RateLimiter(func, *, min_delay_seconds=0.0, max_retries=2, error_wait_seconds=5.0, swallow_exceptions=True, return_value_on_exception=None)

这是用于同步函数（如具有默认 geopy.adapters.BaseSyncAdapter 的地理编码器）的速率限制器实现。

示例

from geopy.extra.rate_limiter import RateLimiter
from geopy.geocoders import Nominatim

geolocator = Nominatim(user_agent="specify_your_app_name_here")

search = ["moscow", "paris", "berlin", "tokyo", "beijing"]
geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1)
locations = [geocode(s) for s in search]

search = [
    (55.47, 37.32), (48.85, 2.35), (52.51, 13.38),
    (34.69, 139.40), (39.90, 116.39)
]
reverse = RateLimiter(geolocator.reverse, min_delay_seconds=1)
locations = [reverse(s) for s in search]

RateLimiter 类是线程安全的。如果地理编码服务的响应比 min_delay_seconds 慢，那么您可以从并行化工作中受益

import concurrent.futures

geolocator = OpenMapQuest(api_key="...")
geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1/20)

with concurrent.futures.ThreadPoolExecutor() as e:
    locations = list(e.map(geocode, search))

在版本 2.0 中更改： 添加了线程安全支持。

__init__(func, *, min_delay_seconds=0.0, max_retries=2, error_wait_seconds=5.0, swallow_exceptions=True, return_value_on_exception=None)
参数

  • func (callable) – 应由速率限制器包装的函数。

  • min_delay_seconds (float) – 包装的 func 调用之间以秒为单位的最小延迟。要将 RPS 速率转换为 min_delay_seconds，您需要用 RPS 除以 1。例如，如果您需要将速率保持在 20 RPS，可以使用 min_delay_seconds=1/20。

  • max_retries (int) – 异常的重试次数。只重试 geopy.exc.GeocoderServiceError 异常 - 其他异常始终会重新引发。每个查询最多执行 max_retries + 1 个请求。设置 max_retries=0 以禁用重试。

  • error_wait_seconds (float) – 错误发生后重试之间等待的时间。必须大于或等于 min_delay_seconds。

  • swallow_exceptions (bool) – 重试后是否应吞并异常？如果不是，则会重新引发异常。如果是，则将返回 return_value_on_exception。

  • return_value_on_exception – 当 swallow_exceptions=True 时，失败时要返回的值。

class geopy.extra.rate_limiter.AsyncRateLimiter(func, *, min_delay_seconds=0.0, max_retries=2, error_wait_seconds=5.0, swallow_exceptions=True, return_value_on_exception=None)

这是一个用于异步函数（如使用 geopy.adapters.BaseAsyncAdapter 的地理编码器）的速率限制器实现。

示例

from geopy.adapters import AioHTTPAdapter
from geopy.extra.rate_limiter import AsyncRateLimiter
from geopy.geocoders import Nominatim

async with Nominatim(
    user_agent="specify_your_app_name_here",
    adapter_factory=AioHTTPAdapter,
) as geolocator:

    search = ["moscow", "paris", "berlin", "tokyo", "beijing"]
    geocode = AsyncRateLimiter(geolocator.geocode, min_delay_seconds=1)
    locations = [await geocode(s) for s in search]

    search = [
        (55.47, 37.32), (48.85, 2.35), (52.51, 13.38),
        (34.69, 139.40), (39.90, 116.39)
    ]
    reverse = AsyncRateLimiter(geolocator.reverse, min_delay_seconds=1)
    locations = [await reverse(s) for s in search]

AsyncRateLimiter 类可以安全地在多个并发任务中使用。如果地理编码服务的响应速度比 min_delay_seconds 慢，那么您可以从并行化工作中受益。

import asyncio

async with OpenMapQuest(
    api_key="...", adapter_factory=AioHTTPAdapter
) as geolocator:

    geocode = AsyncRateLimiter(geolocator.geocode, min_delay_seconds=1/20)
    locations = await asyncio.gather(*(geocode(s) for s in search))

版本 2.0 中的新增功能。

__init__(func, *, min_delay_seconds=0.0, max_retries=2, error_wait_seconds=5.0, swallow_exceptions=True, return_value_on_exception=None)
参数

  • func (callable) – 应由速率限制器包装的函数。

  • min_delay_seconds (float) – 包装的 func 调用之间以秒为单位的最小延迟。要将 RPS 速率转换为 min_delay_seconds，您需要用 RPS 除以 1。例如，如果您需要将速率保持在 20 RPS，可以使用 min_delay_seconds=1/20。

  • max_retries (int) – 异常的重试次数。只重试 geopy.exc.GeocoderServiceError 异常 - 其他异常始终会重新引发。每个查询最多执行 max_retries + 1 个请求。设置 max_retries=0 以禁用重试。

  • error_wait_seconds (float) – 错误发生后重试之间等待的时间。必须大于或等于 min_delay_seconds。

  • swallow_exceptions (bool) – 重试后是否应吞并异常？如果不是，则会重新引发异常。如果是，则将返回 return_value_on_exception。

  • return_value_on_exception – 当 swallow_exceptions=True 时，失败时要返回的值。

ArcGIS

class geopy.geocoders.ArcGIS(username=None, password=None, *, referer=None, token_lifetime=60, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, auth_domain='www.arcgis.com', domain='geocode.arcgis.com')

使用 ERSI ArcGIS API 的地理编码器。

文档地址：

https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm

__init__(username=None, password=None, *, referer=None, token_lifetime=60, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, auth_domain='www.arcgis.com', domain='geocode.arcgis.com')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, out_fields=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • out_fields (str 或 可迭代对象) – 要在原始数据属性字段中返回的输出字段列表。 可以是 Python 列表/元组字段或逗号分隔字符串。 有关支持的输出字段列表，请参阅 https://developers.arcgis.com/rest/geocode/api-reference/geocoding-service-output.htm。 如果要返回所有支持的输出字段，请设置 out_fields="*"。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, distance=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • distance (int) – 查询位置的距离（以米为单位），在此范围内进行搜索。 如果未指定，ArcGIS 的默认值为 100 米。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

AzureMaps

class geopy.geocoders.AzureMaps(subscription_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='atlas.microsoft.com')

Bases: geopy.geocoders.tomtom.TomTom

基于 TomTom 的 AzureMaps 地理编码器。

文档地址：

https://docs.microsoft.com/en-us/azure/azure-maps/index

__init__(subscription_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='atlas.microsoft.com')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None, typeahead=False, language=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 要从服务返回的结果的最大数量。 除非将 exactly_one 设置为 False，否则 limit 将始终为 1。

  • typeahead (bool) – 如果设置了“typeahead”标志，则查询将被解释为部分输入，搜索将进入预测模式。

  • language (str) – 搜索结果应返回的语言。 当指定语言的数据在特定字段不可用时，将使用默认语言。 支持的语言列表（不区分大小写）：https://developer.tomtom.com/online-search/online-search-documentation/supported-languages

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) – 搜索结果应返回的语言。 当指定语言的数据在特定字段不可用时，将使用默认语言。 支持的语言列表（不区分大小写）：https://developer.tomtom.com/online-search/online-search-documentation/supported-languages

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Baidu

class geopy.geocoders.Baidu(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, security_key=None)

使用 Baidu Maps v2 API 的地理编码器。

文档地址：

http://lbsyun.baidu.com/index.php?title=webapi/guide/webservice-geocoding

注意

新注册的 API 密钥无法与 v2 API 一起使用，请改用 BaiduV3。

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, security_key=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。百度 API 始终最多返回一个结果。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

BaiduV3

class geopy.geocoders.BaiduV3(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, security_key=None)

Bases: geopy.geocoders.baidu.Baidu

使用百度地图 v3 API 的地理编码器。

文档地址：

http://lbsyun.baidu.com/index.php?title=webapi/guide/webservice-geocoding

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, security_key=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。百度 API 始终最多返回一个结果。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

BANFrance

class geopy.geocoders.BANFrance(*, domain='api-adresse.data.gouv.fr', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用法国国家地址数据库 API 的地理编码器。

文档地址：

https://adresse.data.gouv.fr/api

__init__(*, domain='api-adresse.data.gouv.fr', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, limit=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • limit (int) – 定义响应结构中项目的最大数量。如果没有提供，并且有多个结果，则 BAN API 默认返回 5 个结果。如果 exactly_one 为 True，则将重置为一个。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Bing

class geopy.geocoders.Bing(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='dev.virtualearth.net')

使用必应地图位置 API 的地理编码器。

文档地址：

https://msdn.microsoft.com/en-us/library/ff701715.aspx

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='dev.virtualearth.net')
参数
geocode(query, *, exactly_one=True, user_location=None, timeout=DEFAULT_SENTINEL, culture=None, include_neighborhood=None, include_country_code=False)

通过地址返回位置点。

参数

  • query (str or dict) –

    您要进行地理编码的地址或查询。

    对于结构化查询，请提供一个字典，其键为以下之一： addressLine、locality（城市）、adminDistrict（州）、countryRegion 或 postalCode。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • user_location (geopy.point.Point) – 优先考虑靠近此位置的结果。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • culture (str) – 影响响应的语言，必须为两位字母的国家代码。

  • include_neighborhood (bool) – 设置是否在响应中包含 neighborhood 字段。

  • include_country_code (bool) – 设置是否在响应中包含国家/地区的两位字母 ISO 代码（字段名称 ‘countryRegionIso2’）。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, culture=None, include_country_code=False)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • culture (str) – 影响响应的语言，必须为两位字母的国家代码。

  • include_country_code (bool) – 设置是否在响应中包含国家/地区的两位字母 ISO 代码（字段名称 ‘countryRegionIso2’）。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

DataBC

class geopy.geocoders.DataBC(*, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='geocoder.api.gov.bc.ca')

使用 DataBC 的物理地址地理编码器进行地理编码。

文档地址：

https://github.com/bcgov/ols-geocoder/blob/gh-pages/geocoder-developer-guide.md

__init__(*, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='geocoder.api.gov.bc.ca')
参数
geocode(query, *, max_results=25, set_back=0, location_descriptor='any', exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • max_results (int) – 请求的最大结果数。

  • set_back (float) – 将 accessPoint 从路边移开（以米为单位）并朝地块内部移动的距离。location_descriptor 必须设置为 accessPoint 才能使 set_back 生效。

  • location_descriptor (str) – 请求的点类型。可以是 any、accessPoint、frontDoorPoint、parcelPoint、rooftopPoint 和 routingPoint。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

GeocodeEarth

class geopy.geocoders.GeocodeEarth(api_key, *, domain='api.geocode.earth', timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, scheme=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

基类：geopy.geocoders.pelias.Pelias

Geocode Earth，由 Pelias 开发人员提供的基于 Pelias 的服务。

文档地址：

https://geocode.earth/docs

定价信息

https://geocode.earth/#pricing

__init__(api_key, *, domain='api.geocode.earth', timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, scheme=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, boundary_rect=None, countries=None, country_bias=None, language=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • boundary_rect (包含 2 个 geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s" 的列表或元组) – 用于限制搜索范围的坐标。例如：[Point(22, 180), Point(-22, -180)]。

  • countries (list) –

    以 ISO 3166-1 alpha-2 或 alpha-3 格式指定的国家代码列表，例如 ['USA', 'CAN']。这是一个硬性筛选条件。

    版本 2.3 新增功能。

  • country_bias (str) –

    将结果偏向此国家（ISO alpha-3）。

    自版本 2.3 起已弃用： 请改用 countries。此选项的行为相同，即它不是一个软性筛选条件，正如其名称所暗示的那样。此参数计划在 geopy 3.0 中移除。

  • language (str) – 返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

GeocodeFarm

版本 2.2 中已更改： 此类已删除，因为该服务过于不可靠。请参阅 #445。

Geocodio

class geopy.geocoders.Geocodio(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain=None)

使用 Geocod.io API 的地理编码器。

文档地址：

https://www.geocod.io/docs/

定价信息

https://www.geocod.io/pricing/

版本 2.2 新增功能。

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain=None)
参数
geocode(query, *, limit=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (dict 或 str) –

    您想要进行地理编码的地址、查询或结构化查询。

    对于结构化查询，请提供一个字典，其键为以下之一：street、city、state、postal_code 或 country。

  • limit (int) – 要返回的最大匹配项数量。如果 exactly_one 为 True，此值将重置为 1。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None)

通过位置点返回地址。

参数

  • query (str) – 您想要获取最接近的人类可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 要返回的最大匹配项数量。如果 exactly_one 为 True，此值将重置为 1。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Geokeo

class geopy.geocoders.Geokeo(api_key, *, domain='geokeo.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 geokeo API 的地理编码器。

文档地址：

https://geokeo.com/documentation.php

新版本：2.4.

__init__(api_key, *, domain='geokeo.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, country=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • country (str) – 将结果限制在指定的国家/地区。国家代码是 ISO 3166-1 Alpha 2 标准定义的 2 个字符代码（例如 us）。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Geolake

class geopy.geocoders.Geolake(api_key, *, domain='api.geolake.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 Geolake API 的地理编码器。

文档地址：

https://geolake.com/docs/api

服务条款在

https://geolake.com/terms-of-use

__init__(api_key, *, domain='api.geolake.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, country_codes=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str or dict) –

    您要进行地理编码的地址或查询。

    对于结构化查询，提供一个字典，其键是以下之一：country、state、city、zipcode、street、address、houseNumber 或 subNumber。

  • country_codes (str or list) – 为地理编码器提供一个国家代码列表，查询可能位于这些国家代码中。此值将限制地理编码器到提供的国家/地区。国家代码是 ISO-3166-1 alpha-2 标准定义的 2 个字符代码（例如 FR）。可以使用 Python 列表指定多个国家/地区。

  • exactly_one (bool) – 返回一个结果或一个结果列表。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

GeoNames

class geopy.geocoders.GeoNames(username, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, scheme='http', domain='api.geonames.org')

GeoNames 地理编码器。

文档地址：

http://www.geonames.org/export/geonames-search.html

反向地理编码文档位于

http://www.geonames.org/export/web-services.html#findNearbyPlaceName

__init__(username, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, scheme='http', domain='api.geonames.org')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, country=None, country_bias=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • country (str or list) – 将记录限制在指定的国家/地区。ISO-3166 的两位字母国家代码（例如 FR）。可以是单个字符串或字符串列表。

  • country_bias (str) – 来自 country_bias 的记录将首先列出。ISO-3166 的两位字母国家代码。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, feature_code=None, lang=None, find_nearby_type='findNearbyPlaceName')

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • feature_code (str) – 一个 GeoNames 特征代码

  • lang (str) – 返回的 name 元素的语言（伪语言代码 ‘local’ 将以本地语言返回）。支持的完整语言列表可在以下网址找到：https://www.geonames.org/countries/

  • find_nearby_type (str) – 用于在不同的 GeoNames API 端点之间切换的标志。默认值为 findNearbyPlaceName，它返回最近的人口稠密地点。当前实现的另一个选项是 findNearby，它返回最靠近 lat/lng 查询的地名。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse_timezone(query, *, timeout=DEFAULT_SENTINEL)

查找 query 中某一点的时区。

GeoNames 始终返回一个时区：如果所查询的点没有分配的 Olson 时区 ID，则使用 pytz.FixedOffset 时区来生成 geopy.timezone.Timezone。

参数

  • query (geopy.point.Point, list 或 tuple of (latitude, longitude)，或字符串如 “%(latitude)s, %(longitude)s”) – 您想要查找时区的坐标。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

geopy.timezone.Timezone.

GoogleV3

class geopy.geocoders.GoogleV3(api_key=None, *, domain='maps.googleapis.com', scheme=None, client_id=None, secret_key=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, channel='')

使用 Google Maps v3 API 的地理编码器。

文档地址：

https://developers.google.com/maps/documentation/geocoding/

定价信息

https://developers.google.com/maps/documentation/geocoding/usage-and-billing

__init__(api_key=None, *, domain='maps.googleapis.com', scheme=None, client_id=None, secret_key=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, channel='')
参数
geocode(query=None, *, exactly_one=True, timeout=DEFAULT_SENTINEL, bounds=None, region=None, components=None, place_id=None, language=None, sensor=False)

通过地址返回位置点。

参数

  • query (str) –

    您要进行地理编码的地址或查询。可选，如果设置了 components 参数

    >>> g.geocode(components={"city": "Paris", "country": "FR"})
Location(France, (46.227638, 2.213749, 0.0))

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • bounds (list 或 tuple of 2 个 geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 用于更突出地偏向地理编码结果的视窗的边界框。示例：[Point(22, 180), Point(-22, -180)]。

  • region (str) – 指定为 ccTLD（“顶级域名”）两位字符值的区域代码。

  • components (dict 或 list) –

    限制在某一区域。可以使用任何组合：route、locality、administrative_area、postal_code、country。

    如果您要指定同一类型的多个组件，请传递一个元组列表，例如：

    >>> [('administrative_area', 'VA'), ('administrative_area', 'Arlington')]

  • place_id (str) –

    使用位置 ID 检索位置。不能与 query 或 bounds 参数一起使用。

    >>> g.geocode(place_id='ChIJOcfP0Iq2j4ARDrXUa7ZWs34')

  • language (str) – 返回结果的语言。

  • sensor (bool) – 地理编码请求是否来自具有位置传感器的设备。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None, sensor=False)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) – 返回结果的语言。

  • sensor (bool) – 地理编码请求是否来自具有位置传感器的设备。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse_timezone(query, *, at_time=None, timeout=DEFAULT_SENTINEL)

查找query中某个点在指定at_time所在的时区。

对于没有分配 Olson 时区 ID 的点（例如南极洲），将返回None。

参数

  • query (geopy.point.Point, list 或 tuple of (latitude, longitude)，或字符串如 “%(latitude)s, %(longitude)s”) – 您想要查找时区的坐标。

  • at_time (datetime.datetime or None) – 您想要查询该位置的时区的时间。此参数可选，默认值为函数调用时的 UTC 时间。支持时区感知日期时间，并会静默地将无时区日期时间视为 UTC。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None 或 geopy.timezone.Timezone.

HERE

class geopy.geocoders.Here(*, app_id=None, app_code=None, apikey=None, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 HERE Geocoder API 的地理编码器。

文档地址：

https://developer.here.com/documentation/geocoder/

注意

此类使用处于维护模式的 v6 API。考虑使用更新的 HereV7 类。

__init__(*, app_id=None, app_code=None, apikey=None, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, bbox=None, mapview=None, exactly_one=True, maxresults=None, pageinformation=None, language=None, additional_data=False, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

此实现仅支持部分可用参数。有关纯 REST API 的所有参数的列表，请访问： https://developer.here.com/documentation/geocoder/topics/resource-geocode.html

参数

  • query (str or dict) –

    您要进行地理编码的地址或查询。

    对于结构化查询，请提供一个字典，其键为以下之一：city、county、district、country、state、street、housenumber 或 postalcode。

  • bbox (list 或 tuple of 2 items of geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 一种空间过滤器，限制请求中对其他属性的搜索。由两个坐标 (lat/lon) 对指定 - 框的角点。bbox 搜索目前类似于 mapview 但不会扩展（引自 REST API 文档）。还将返回相关的全局结果。示例：[Point(22, 180), Point(-22, -180)]。

  • mapview (list 或 tuple of 2 items of geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 应用程序的视窗，以两个坐标对的形式给出，由两个 lat/lon 对指定 - 分别为边界框的角点。来自地图视窗内以及扩展区域的匹配结果将排名最高。还将返回相关的全局结果。示例：[Point(22, 180), Point(-22, -180)]。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • maxresults (int) – 定义响应结构中的最大项目数。如果未提供且存在多个结果，HERE API 默认将返回 10 个结果。如果 exactly_one 为 True，则将重置为 1。

  • pageinformation (int) – 当响应被分成多个页面时，用于标识要返回的页面的键。仅当也提供 maxresults 时才有用。

  • language (str) – 影响响应的语言，必须为 RFC 4647 语言代码，例如‘en-US’。

  • additional_data (str) – 包含键值对的字符串，如 https://developer.here.com/documentation/geocoder/topics/resource-params-additional.html 中所述。这些将被作为 URL 的一个查询参数添加。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, radius=None, exactly_one=True, maxresults=None, pageinformation=None, language=None, mode='retrieveAddresses', timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

此实现仅支持所有可用参数的子集。所有纯 REST API 参数的列表可在此处获取：https://developer.here.com/documentation/geocoder/topics/resource-reverse-geocode.html

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • radius (float) – 以米为单位的邻近半径。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • maxresults (int) – 定义响应结构中的最大项目数。如果未提供且存在多个结果，HERE API 默认将返回 10 个结果。如果 exactly_one 为 True，则将重置为 1。

  • pageinformation (int) – 当响应被分成多个页面时，用于标识要返回的页面的键。仅当也提供 maxresults 时才有用。

  • language (str) – 影响响应的语言，必须为 RFC 4647 语言代码，例如‘en-US’。

  • mode (str) – 影响返回的响应项类型，必须为以下之一：“retrieveAddresses”（默认）、“retrieveAreas”、“retrieveLandmarks”、“retrieveAll”或“trackPosition”。有关详细信息，请参阅在线文档。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

HEREv7

class geopy.geocoders.HereV7(apikey, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='search.hereapi.com')

使用 HERE 地理编码和搜索 v7 API 的地理编码器。

文档地址：

https://developer.here.com/documentation/geocoding-search-api/

服务条款在

https://legal.here.com/en-gb/terms

版本 2.2 新增功能。

__init__(apikey, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='search.hereapi.com')
参数
geocode(query=None, *, components=None, at=None, countries=None, language=None, limit=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您要进行地理编码的地址或查询。可选，如果设置了components参数。

  • components (dict) – 结构化查询。可与自由文本query一起使用。应为一个字典，其键为以下之一：“country”、“state”、“county”、“city”、“district”、“street”、“houseNumber”、“postalCode”。

  • at (geopy.point.Point，(latitude, longitude) 的列表或元组，或字符串格式为"%(latitude)s, %(longitude)s".) – 搜索上下文的中心。

  • countries (list) – 以ISO 3166-1 alpha-3格式指定的国家代码列表，例如['USA', 'CAN']。这是一个硬性过滤器。

  • language (str) – 影响响应的语言，必须为符合 BCP 47 的语言代码，例如en-US。

  • limit (int) – 定义响应结构中的项目最大数量。如果未提供且存在多个结果，则 HERE API 默认返回 20 个结果。如果exactly_one为 True，则将重置为 1。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, language=None, limit=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • language (str) – 影响响应的语言，必须为符合 BCP 47 的语言代码，例如en-US。

  • limit (int) – 要返回的结果最大数量。如果exactly_one为 True，则将重置为 1。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

IGNFrance

class geopy.geocoders.IGNFrance(api_key=None, *, username=None, password=None, referer=None, domain='wxs.ign.fr', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 IGN 法国 GeoCoder OpenLS API 的地理编码器。

文档地址：

https://geoservices.ign.fr/services-web-essentiels

__init__(api_key=None, *, username=None, password=None, referer=None, domain='wxs.ign.fr', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, query_type='StreetAddress', maximum_responses=25, is_freeform=False, filtering=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 要进行地理编码的查询字符串。

  • query_type (str) – 用于地理编码的类型。可以是 PositionOfInterest、StreetAddress 或 CadastralParcel。如果没有提供，则默认选择 StreetAddress。

  • maximum_responses (int) – 查询正文中请求 API 的最大响应数。

  • is_freeform (str) – 设置返回是否具有自由格式结构或更结构化的返回。默认情况下，值为 False。

  • filtering (str) – 提供帮助设置地理编码器过滤器的字符串。它包含一个 XML 字符串。在文档和 tests 目录中的 ignfrance.py 文件中查看示例。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, reverse_geocode_preference=('StreetAddress',), maximum_responses=25, filtering='', exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • reverse_geocode_preference (list) – 启用以设置预期的结果类型。可以是 StreetAddress 或 PositionOfInterest。默认设置为 StreetAddress。

  • maximum_responses (int) – 查询正文中请求 API 的最大响应数。

  • filtering (str) – 提供帮助设置地理编码器过滤器的字符串。它包含一个 XML 字符串。在文档和 tests 目录中的 ignfrance.py 文件中查看示例。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

MapBox

class geopy.geocoders.MapBox(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.mapbox.com', referer=None)

使用 Mapbox API 的地理编码器。

文档地址：

https://www.mapbox.com/api-documentation/

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.mapbox.com', referer=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, proximity=None, country=None, language=None, bbox=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • proximity (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串作为 "%(latitude)s, %(longitude)s".) – 基于提供的地理位置偏差本地结果的坐标。

  • country (str 或 list) – 以 ISO 3166-1 alpha-2 国家代码形式过滤结果的国家/地区（例如 FR）。可以是 Python 字符串列表。

  • language (str) –

    此参数控制响应中提供的文本的语言，也影响结果评分，与用户在请求语言中查询匹配的结果优先于以其他语言匹配的结果。您可以传递两个字母的国家/地区代码（ISO 639-1）。

    版本 2.3 新增功能。

  • bbox (geopy.point.Point 或 (latitude, longitude) 的列表或元组，或字符串作为 "%(latitude)s, %(longitude)s".) – 视窗的边界框，在其中更突出地偏差地理编码结果。例如：[Point(22, 180), Point(-22, -180)]。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

MapQuest

class geopy.geocoders.MapQuest(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='www.mapquestapi.com')

使用基于许可数据的 MapQuest API 的地理编码器。

文档地址：

https://developer.mapquest.com/documentation/geocoding-api/

MapQuest 提供两种地理编码 API

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='www.mapquestapi.com')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None, bounds=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 限制响应中项目的最大数量。如果 exactly_one 为 True，则将其重置为 1。

  • bounds (list 或 tuple of 2 个 geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 用于更突出地偏向地理编码结果的视窗的边界框。示例：[Point(22, 180), Point(-22, -180)]。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

MapTiler

class geopy.geocoders.MapTiler(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.maptiler.com')

使用 MapTiler API 的地理编码器。

文档地址：

https://cloud.maptiler.com/geocoding/ (需要注册)

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.maptiler.com')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, proximity=None, language=None, bbox=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • proximity (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串作为 "%(latitude)s, %(longitude)s".) – 基于提供的地理位置偏差本地结果的坐标。

  • language (str or list) – 优先考虑特定语言的结果。接受单个字符串，例如 "en" 或列表，例如 ["de", "en"]。

  • bbox (geopy.point.Point 或 (latitude, longitude) 的列表或元组，或字符串作为 "%(latitude)s, %(longitude)s".) – 视窗的边界框，在其中更突出地偏差地理编码结果。例如：[Point(22, 180), Point(-22, -180)]。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str or list) – 优先考虑特定语言的结果。接受单个字符串，例如 "en" 或列表，例如 ["de", "en"]。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

OpenCage

class geopy.geocoders.OpenCage(api_key, *, domain='api.opencagedata.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 OpenCageData API 的地理编码器。

文档地址：

https://opencagedata.com/api

版本 2.2 中的变更: 通过使用默认错误映射改进了错误处理（例如，针对 HTTP 402 错误，将引发 exc.GeocoderQuotaExceeded 而不是 exc.GeocoderQueryError）。

__init__(api_key, *, domain='api.opencagedata.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, bounds=None, country=None, language=None, annotations=True, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • bounds (list 或包含 2 个 geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s" 的元组) – 为地理编码器提供查询所在的区域提示。此值将帮助地理编码器，但不会将可能的查询结果限制到提供的区域。bounds 参数应指定为 2 个坐标点 - 包围盒的角点。例如：[Point(22, 180), Point(-22, -180)]。

  • country (str 或 list) – 将结果限制在指定国家或国家。国家代码是 ISO 3166-1 Alpha 2 标准定义的 2 个字符代码（例如 fr）。可能是字符串的 Python 列表。

  • language (str) – IETF 格式语言代码（例如 es 表示西班牙语或 pt-BR 表示巴西葡萄牙语）；如果省略，远程服务将假定代码为 en（英语）。

  • annotations (bool) –

    启用 注释 数据，可以通过 Location.raw 访问。如果您不需要注释数据，可以将其设置为 False 以获得少许性能提升。

    版本 2.2 新增功能。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, language=None, exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • language (str) – 返回结果的语言。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

OpenMapQuest

class geopy.geocoders.OpenMapQuest(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='open.mapquestapi.com', scheme=None, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

继承自：geopy.geocoders.nominatim.Nominatim

使用 MapQuest Open Platform Web 服务的地理编码器。

文档地址：

https://developer.mapquest.com/documentation/open/

MapQuest 提供两种地理编码 API

__init__(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='open.mapquestapi.com', scheme=None, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None, addressdetails=False, language=False, geometry=None, extratags=False, country_codes=None, viewbox=None, bounded=False, featuretype=None, namedetails=False)

通过地址返回位置点。

参数

  • query (dict 或 str) –

    您想要进行地理编码的地址、查询或结构化查询。

    对于结构化查询，请提供一个字典，其键为以下之一：street、city、county、state、country 或 postalcode。有关更多信息，请参阅 Nominatim 的 结构化请求 文档

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 从 Nominatim 返回的最大结果数。除非将 exactly_one 设置为 False，否则 limit 将始终为 1。

  • addressdetails (bool) – 如果您希望在 Location.raw 中包含地址详细信息，例如房屋编号、城市区、邮政编码等（以结构化形式），则将其设置为 True

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

  • geometry (str) – 如果存在，则指定地理编码服务是否应在 wkt、svg、kml 或 geojson 格式中返回结果的几何形状。这可通过返回的 geopy.location.Location 对象上的 raw 属性获得。

  • extratags (bool) – 如果可用，请在结果中包含其他信息，例如维基百科链接、营业时间。

  • country_codes (str 或 list) – 将搜索结果限制到特定国家/地区（或国家/地区列表）。国家/地区代码应为 ISO 3166-1alpha2 代码，例如 gb 代表英国，de 代表德国等。

  • viewbox (包含 geopy.point.Point 的 2 个项目的列表或元组，或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 优先考虑此区域以查找搜索结果。默认情况下，这被视为提示，如果要将结果限制在此区域内，请同时指定 bounded=True。例如：[Point(22, 180), Point(-22, -180)]。

  • bounded (bool) – 将结果限制为仅包含在边界 viewbox 内的项目。

  • featuretype (str) – 如果存在，则将结果限制为特定类型的要素。允许的值：country、state、city、settlement。

  • namedetails (bool) – 如果您希望在 Location.raw 中包含 namedetails，请将其设置为 True。这将是一个替代名称列表，包括语言变体等。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=False, addressdetails=True, zoom=None, namedetails=False)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

  • addressdetails (bool) – 是否在 Location.raw 中包含地址详细信息，例如城市、县、州等。

  • zoom (int) – 地址所需的详细程度，范围从 0（国家/地区级别）到 18（建筑级别）的整数，默认为 18。

  • namedetails (bool) –

    如果希望在 Location.raw 中包含 namedetails，请将其设置为 True。这将是一个替代名称列表，包括语言变体等。

    版本 2.3 新增功能。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Nominatim

class geopy.geocoders.Nominatim(*, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='nominatim.openstreetmap.org', scheme=None, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

用于 OpenStreetMap 数据的 Nominatim 地理编码器。

文档地址：

https://nominatim.org/release-docs/develop/api/Overview/

注意

强烈建议不要使用 Nominatim 和默认的 user_agent，因为它违反了 Nominatim 的使用政策 https://operations.osmfoundation.org/policies/nominatim/，并且可能会导致 403 和 429 HTTP 错误。请确保使用 Nominatim(user_agent="my-application") 指定自定义 user_agent，或者通过覆盖默认的 user_agent：geopy.geocoders.options.default_user_agent = "my-application"。如果没有指定自定义 user_agent，则会抛出异常。

__init__(*, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='nominatim.openstreetmap.org', scheme=None, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None, addressdetails=False, language=False, geometry=None, extratags=False, country_codes=None, viewbox=None, bounded=False, featuretype=None, namedetails=False)

通过地址返回位置点。

参数

  • query (dict 或 str) –

    您想要进行地理编码的地址、查询或结构化查询。

    对于结构化查询，请提供一个字典，其键为以下之一：street、city、county、state、country 或 postalcode。有关更多信息，请参阅 Nominatim 的 结构化请求 文档

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 从 Nominatim 返回的最大结果数。除非将 exactly_one 设置为 False，否则 limit 将始终为 1。

  • addressdetails (bool) – 如果您希望在 Location.raw 中包含地址详细信息，例如房屋编号、城市区、邮政编码等（以结构化形式），则将其设置为 True

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

  • geometry (str) – 如果存在，则指定地理编码服务是否应在 wkt、svg、kml 或 geojson 格式中返回结果的几何形状。这可通过返回的 geopy.location.Location 对象上的 raw 属性获得。

  • extratags (bool) – 如果可用，请在结果中包含其他信息，例如维基百科链接、营业时间。

  • country_codes (str 或 list) – 将搜索结果限制到特定国家/地区（或国家/地区列表）。国家/地区代码应为 ISO 3166-1alpha2 代码，例如 gb 代表英国，de 代表德国等。

  • viewbox (包含 geopy.point.Point 的 2 个项目的列表或元组，或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 优先考虑此区域以查找搜索结果。默认情况下，这被视为提示，如果要将结果限制在此区域内，请同时指定 bounded=True。例如：[Point(22, 180), Point(-22, -180)]。

  • bounded (bool) – 将结果限制为仅包含在边界 viewbox 内的项目。

  • featuretype (str) – 如果存在，则将结果限制为特定类型的要素。允许的值：country、state、city、settlement。

  • namedetails (bool) – 如果您希望在 Location.raw 中包含 namedetails，请将其设置为 True。这将是一个替代名称列表，包括语言变体等。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=False, addressdetails=True, zoom=None, namedetails=False)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

  • addressdetails (bool) – 是否在 Location.raw 中包含地址详细信息，例如城市、县、州等。

  • zoom (int) – 地址所需的详细程度，范围从 0（国家/地区级别）到 18（建筑级别）的整数，默认为 18。

  • namedetails (bool) –

    如果希望在 Location.raw 中包含 namedetails，请将其设置为 True。这将是一个替代名称列表，包括语言变体等。

    版本 2.3 新增功能。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Pelias

class geopy.geocoders.Pelias(domain, api_key=None, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, scheme=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

Pelias 地理编码器。

文档地址：

https://github.com/pelias/documentation

另请参阅 geopy.geocoders.GeocodeEarth，它是 Pelias 开发人员提供的基于 Pelias 的服务。

__init__(domain, api_key=None, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, scheme=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, boundary_rect=None, countries=None, country_bias=None, language=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • boundary_rect (包含 2 个 geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s" 的列表或元组) – 用于限制搜索范围的坐标。例如：[Point(22, 180), Point(-22, -180)]。

  • countries (list) –

    以 ISO 3166-1 alpha-2 或 alpha-3 格式指定的国家代码列表，例如 ['USA', 'CAN']。这是一个硬性筛选条件。

    版本 2.3 新增功能。

  • country_bias (str) –

    将结果偏向此国家（ISO alpha-3）。

    自版本 2.3 起已弃用： 请改用 countries。此选项的行为相同，即它不是一个软性筛选条件，正如其名称所暗示的那样。此参数计划在 geopy 3.0 中移除。

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Photon

class geopy.geocoders.Photon(*, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='photon.komoot.io', user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 Photon 地理编码服务（数据基于 OpenStreetMap，服务由 Komoot 在 https://photon.komoot.io 提供）的地理编码器。

文档地址：

https://github.com/komoot/photon

Photon/Komoot 地理编码器旨在让你 边输入边搜索 OpenStreetMap。 此平台不需要 API 密钥。

Changed in version 2.2: 将默认域名从 photon.komoot.de 更改为 photon.komoot.io。

__init__(*, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='photon.komoot.io', user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, location_bias=None, language=False, limit=None, osm_tag=None, bbox=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • location_bias (geopy.point.Point, list 或 tuple of (latitude, longitude)，或 string as "%(latitude)s, %(longitude)s".) – 用作位置偏差的坐标。

  • language (str) – 返回结果的首选语言。

  • limit (int) – 限制返回结果的数量，默认无限制。

  • osm_tag (str 或 list 或 set) – 用于通过键和/或值进行过滤（包含/排除）的表达式，str 形式为 'key:value'，如果需要多个过滤器，则 list/set of str 形式为 ['key:!val', '!key', ':!value']。

  • bbox (list 或 tuple of 2 items of geopy.point.Point 或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) –

    用于更突出地偏差地理编码结果的视窗的边界框。示例：[Point(22, 180), Point(-22, -180)]。

    版本 2.2 新增功能。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=False, limit=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) – 返回结果的首选语言。

  • limit (int) – 限制返回结果的数量，默认无限制。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

PickPoint

class geopy.geocoders.PickPoint(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='api.pickpoint.io', scheme=None, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

继承自：geopy.geocoders.nominatim.Nominatim

PickPoint 地理编码器是 Nominatim 的商业版本。

文档地址：

https://pickpoint.io/api-reference

__init__(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, domain='api.pickpoint.io', scheme=None, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None, addressdetails=False, language=False, geometry=None, extratags=False, country_codes=None, viewbox=None, bounded=False, featuretype=None, namedetails=False)

通过地址返回位置点。

参数

  • query (dict 或 str) –

    您想要进行地理编码的地址、查询或结构化查询。

    对于结构化查询，请提供一个字典，其键为以下之一：street、city、county、state、country 或 postalcode。有关更多信息，请参阅 Nominatim 的 结构化请求 文档

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 从 Nominatim 返回的最大结果数。除非将 exactly_one 设置为 False，否则 limit 将始终为 1。

  • addressdetails (bool) – 如果您希望在 Location.raw 中包含地址详细信息，例如房屋编号、城市区、邮政编码等（以结构化形式），则将其设置为 True

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

  • geometry (str) – 如果存在，则指定地理编码服务是否应在 wkt、svg、kml 或 geojson 格式中返回结果的几何形状。这可通过返回的 geopy.location.Location 对象上的 raw 属性获得。

  • extratags (bool) – 如果可用，请在结果中包含其他信息，例如维基百科链接、营业时间。

  • country_codes (str 或 list) – 将搜索结果限制到特定国家/地区（或国家/地区列表）。国家/地区代码应为 ISO 3166-1alpha2 代码，例如 gb 代表英国，de 代表德国等。

  • viewbox (包含 geopy.point.Point 的 2 个项目的列表或元组，或 (latitude, longitude) 或 "%(latitude)s, %(longitude)s".) – 优先考虑此区域以查找搜索结果。默认情况下，这被视为提示，如果要将结果限制在此区域内，请同时指定 bounded=True。例如：[Point(22, 180), Point(-22, -180)]。

  • bounded (bool) – 将结果限制为仅包含在边界 viewbox 内的项目。

  • featuretype (str) – 如果存在，则将结果限制为特定类型的要素。允许的值：country、state、city、settlement。

  • namedetails (bool) – 如果您希望在 Location.raw 中包含 namedetails，请将其设置为 True。这将是一个替代名称列表，包括语言变体等。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=False, addressdetails=True, zoom=None, namedetails=False)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) –

    返回结果的首选语言。可以使用标准的 RFC2616 accept-language 字符串或简单的逗号分隔的语言代码列表。

  • addressdetails (bool) – 是否在 Location.raw 中包含地址详细信息，例如城市、县、州等。

  • zoom (int) – 地址所需的详细程度，范围从 0（国家/地区级别）到 18（建筑级别）的整数，默认为 18。

  • namedetails (bool) –

    如果希望在 Location.raw 中包含 namedetails，请将其设置为 True。这将是一个替代名称列表，包括语言变体等。

    版本 2.3 新增功能。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

LiveAddress

class geopy.geocoders.LiveAddress(auth_id, auth_token, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 SmartyStreets 提供的 LiveAddress API 的地理编码器。

文档地址：

https://smartystreets.com/docs/cloud/us-street-api

__init__(auth_id, auth_token, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, candidates=1)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • candidates (int) – 一个介于 1 到 10 之间的整数，表示如果找到有效地址，要返回的候选地址的最大数量。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

TomTom

class geopy.geocoders.TomTom(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.tomtom.com')

TomTom 地理编码器。

文档地址：

https://developer.tomtom.com/search-api/search-api-documentation

__init__(api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.tomtom.com')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, limit=None, typeahead=False, language=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • limit (int) – 要从服务返回的结果的最大数量。 除非将 exactly_one 设置为 False，否则 limit 将始终为 1。

  • typeahead (bool) – 如果设置了“typeahead”标志，则查询将被解释为部分输入，搜索将进入预测模式。

  • language (str) – 搜索结果应返回的语言。 当指定语言的数据在特定字段不可用时，将使用默认语言。 支持的语言列表（不区分大小写）：https://developer.tomtom.com/online-search/online-search-documentation/supported-languages

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) – 搜索结果应返回的语言。 当指定语言的数据在特定字段不可用时，将使用默认语言。 支持的语言列表（不区分大小写）：https://developer.tomtom.com/online-search/online-search-documentation/supported-languages

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

What3Words

class geopy.geocoders.What3Words(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.what3words.com')

使用旧版 V2 API 的 What3Words 地理编码器。

文档地址：

https://docs.what3words.com/api/v2/

注意

建议使用 What3WordsV3。

__init__(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.what3words.com')
参数
geocode(query, *, lang='en', exactly_one=True, timeout=DEFAULT_SENTINEL)

返回 3 个单词 查询的地址位置。如果 3 个单词 地址不存在，则会抛出 geopy.exc.GeocoderQueryError 异常。

参数

  • query (str) – 您要进行地理编码的 3 个单词地址。

  • lang (str) – API 支持的两位字符语言代码 (https://docs.what3words.com/api/v2/#lang).

  • exactly_one (bool) – 返回一个结果或多个结果（如果可用）。由于地址方案，每个 3 个单词 地址始终只有一个结果，因此此参数对该地理编码器来说毫无用处。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

geopy.location.Location 或多个结果列表（如果 exactly_one=False）。

reverse(query, *, lang='en', exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回 3 个单词 地址。表面上的每个点都有一个 3 个单词 地址，因此始终有非空响应。

参数

  • query (geopy.point.Point、(latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您要获取 3 个单词地址的坐标。

  • lang (str) – API 支持的两位字符语言代码 (https://docs.what3words.com/api/v2/#lang).

  • exactly_one (bool) – 返回一个结果或多个结果（如果可用）。由于地址方案，每个 3 个单词 地址始终只有一个结果，因此此参数对该地理编码器来说毫无用处。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

geopy.location.Location 或多个结果列表（如果 exactly_one=False）。

What3WordsV3

class geopy.geocoders.What3WordsV3(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.what3words.com')

使用 V3 API 的 What3Words 地理编码器。

文档地址：

https://developer.what3words.com/public-api/docs

版本 2.2 新增功能。

__init__(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='api.what3words.com')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL)

返回 3 个单词 查询的地址位置。如果 3 个单词 地址不存在，则会抛出 geopy.exc.GeocoderQueryError 异常。

参数

  • query (str) – 您要进行地理编码的 3 个单词地址。

  • exactly_one (bool) – 返回一个结果或多个结果（如果可用）。由于地址方案，每个 3 个单词 地址始终只有一个结果，因此此参数对该地理编码器来说毫无用处。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

geopy.location.Location 或多个结果列表（如果 exactly_one=False）。

reverse(query, *, lang='en', exactly_one=True, timeout=DEFAULT_SENTINEL)

通过位置点返回 3 个单词 地址。表面上的每个点都有一个 3 个单词 地址，因此始终有非空响应。

参数

  • query (geopy.point.Point、(latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您要获取 3 个单词地址的坐标。

  • lang (str) – API 支持的两位字符语言代码 (https://developer.what3words.com/public-api/docs#available-languages).

  • exactly_one (bool) – 返回一个结果或多个结果（如果可用）。由于地址方案，每个 3 个单词 地址始终只有一个结果，因此此参数对该地理编码器来说毫无用处。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

返回类型

geopy.location.Location 或多个结果列表（如果 exactly_one=False）。

Woosmap

class geopy.geocoders.Woosmap(api_key, *, domain='api.woosmap.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)

使用 Woosmap 地址 API 的地理编码器。

文档地址：

https://developers.woosmap.com/products/address-api/geocode/

新版本：2.4.

__init__(api_key, *, domain='api.woosmap.com', scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None)
参数
geocode(query, *, limit=None, exactly_one=True, timeout=DEFAULT_SENTINEL, location=None, components=None, language=None, country_code_format=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址。

  • limit (int) – 要返回的结果最大数量。如果exactly_one为 True，则将重置为 1。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • location (geopy.point.Point, list or tuple of (latitude, longitude), or string as "%(latitude)s, %(longitude)s".) – 用于偏置搜索上下文的中心经纬度。

  • components (dict 或 list) –

    您想要限制结果的地理位置。 目前，您可以使用组件来过滤国家/地区。 国家/地区由两位字符的 ISO 3166-1 Alpha-2 或三位字符的 ISO 3166-1 Alpha-3 兼容国家/地区代码标识。

    如果您要指定同一类型的多个组件，请传递一个元组列表，例如：

    >>> [('country', 'FRA'), ('country', 'DE')]

  • language (str) – 返回结果的语言。 必须是 ISO 639-1 语言代码。

  • country_code_format (str) – 响应中的默认国家/地区代码格式为 Alpha3。 但是，可以通过在 alpha2 中指定组件来更改响应中的格式。 可用格式： alpha2, alpha3。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, limit=None, exactly_one=True, timeout=DEFAULT_SENTINEL, language=None, country_code_format=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • limit (int) – 要返回的结果最大数量。如果exactly_one为 True，则将重置为 1。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • language (str) – 返回结果的语言。

  • country_code_format (str) – 响应中的默认国家/地区代码格式为 Alpha3。 但是，可以通过在 alpha2 中指定组件来更改响应中的格式。 可用格式： alpha2, alpha3。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

Yandex

class geopy.geocoders.Yandex(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, scheme=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='geocode-maps.yandex.ru')

Yandex 地理编码器。

文档地址：

https://tech.yandex.com/maps/doc/geocoder/desc/concepts/input_params-docpage/

__init__(api_key, *, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, scheme=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None, domain='geocode-maps.yandex.ru')
参数
geocode(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, lang=None)

通过地址返回位置点。

参数

  • query (str) – 您想要进行地理编码的地址或查询。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • lang (str) –

    响应语言和地图的区域设置。 支持的值列表

    • tr_TR – 土耳其语（仅限土耳其地图）；

    • en_RU – 英语响应，俄罗斯地图特征；

    • en_US – 英语响应，美国地图特征；

    • ru_RU – 俄语（默认）；

    • uk_UA – 乌克兰语；

    • be_BY – 白俄罗斯语。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

reverse(query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, kind=None, lang=None)

通过位置点返回地址。

参数

  • query (geopy.point.Point, (latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 您想要获取最接近的可读地址的坐标。

  • exactly_one (bool) – 返回一个结果或一个结果列表（如果可用）。

  • timeout (int) – 在引发 geopy.exc.GeocoderTimedOut 异常之前，等待地理编码服务响应的时间（以秒为单位）。仅当您希望覆盖地理编码器初始化期间设置的值时，才设置此值。

  • kind (str) – 地名的类型。 允许的值： house, street, metro, district, locality.

  • lang (str) –

    响应语言和地图的区域设置。 支持的值列表

    • tr_TR – 土耳其语（仅限土耳其地图）；

    • en_RU – 英语响应，俄罗斯地图特征；

    • en_US – 英语响应，美国地图特征；

    • ru_RU – 俄语（默认）；

    • uk_UA – 乌克兰语；

    • be_BY – 白俄罗斯语。

返回类型

None, geopy.location.Location 或者它们的列表，如果 exactly_one=False。

计算距离

Geopy 可以使用 测地距离 或 大圆距离 计算两个点之间的距离，默认情况下使用测地距离，作为函数 geopy.distance.distance 提供。

大圆距离 (great_circle) 使用地球的球面模型，使用国际大地测量与地球物理联合会定义的平均地球半径，(2a + b)/3 = 6371.0087714150598 公里，约 6371.009 公里（对于 WGS-84），产生的误差最多约为 0.5%。 半径值存储在 distance.EARTH_RADIUS 中，因此可以自定义（但是，它应该始终以公里为单位）。

测地距离是地球椭球模型表面上的最短距离。 默认算法使用 Karney (2013) (geodesic) 给出的方法； 这种方法的精度达到舍入误差，并且始终收敛。

geopy.distance.distance 当前使用 geodesic.

存在多种流行的椭球模型，哪种模型最准确取决于您的点在地球上的位置。 默认情况下为 WGS-84 椭球，该椭球在全球范围内最为精确。 geopy 在 distance.ELLIPSOIDS 字典中包含其他几种模型

              model             major (km)   minor (km)     flattening
ELLIPSOIDS = {'WGS-84':        (6378.137,    6356.7523142,  1 / 298.257223563),
              'GRS-80':        (6378.137,    6356.7523141,  1 / 298.257222101),
              'Airy (1830)':   (6377.563396, 6356.256909,   1 / 299.3249646),
              'Intl 1924':     (6378.388,    6356.911946,   1 / 297.0),
              'Clarke (1880)': (6378.249145, 6356.51486955, 1 / 293.465),
              'GRS-67':        (6378.1600,   6356.774719,   1 / 298.25),
              }

以下是一些 distance.distance 使用示例，以 (lat, lon) 元组对的形式。

>>> from geopy import distance
>>> newport_ri = (41.49008, -71.312796)
>>> cleveland_oh = (41.499498, -81.695391)
>>> print(distance.distance(newport_ri, cleveland_oh).miles)
538.39044536

>>> wellington = (-41.32, 174.81)
>>> salamanca = (40.96, -5.50)
>>> print(distance.distance(wellington, salamanca).km)
19959.6792674

使用 great_circle 距离

>>> print(distance.great_circle(newport_ri, cleveland_oh).miles)
536.997990696

您可以按如下方式更改测地公式使用的椭球模型

>>> ne, cl = newport_ri, cleveland_oh
>>> print(distance.geodesic(ne, cl, ellipsoid='GRS-80').miles)

上述模型名称将自动从 distance.ELLIPSOIDS 字典中检索。或者，您可以直接指定模型值。

>>> distance.geodesic(ne, cl, ellipsoid=(6377., 6356., 1 / 297.)).miles

距离支持简单的算术运算，这使得计算路径长度等操作变得容易。

>>> from geopy import Nominatim
>>> d = distance.distance
>>> g = Nominatim(user_agent="specify_your_app_name_here")
>>> _, wa = g.geocode('Washington, DC')
>>> _, pa = g.geocode('Palo Alto, CA')
>>> print((d(ne, cl) + d(cl, wa) + d(wa, pa)).miles)
3277.30439191

目前，所有算法都假设点的海拔高度为零（如上例所示）或相等，且相对较小。因此，海拔高度不会影响最终的距离。

>>> from geopy import distance
>>> newport_ri = (41.49008, -71.312796)
>>> cleveland_oh = (41.499498, -81.695391)
>>> print(distance.distance(newport_ri, cleveland_oh).km)
866.4554329098687
>>> newport_ri = (41.49008, -71.312796, 100)
>>> cleveland_oh = (41.499498, -81.695391, 100)
>>> print(distance.distance(newport_ri, cleveland_oh).km)
866.4554329098687

如果您需要计算有海拔高度的距离，那么对于短距离来说，欧氏距离 公式可能可以提供一个合适的近似值。

>>> import math
>>> from geopy import distance
>>> p1 = (43.668613, 40.258916, 0.976)
>>> p2 = (43.658852, 40.250839, 1.475)
>>> flat_distance = distance.distance(p1[:2], p2[:2]).km
>>> print(flat_distance)
1.265133525952866
>>> euclidian_distance = math.sqrt(flat_distance**2 + (p2[2] - p1[2])**2)
>>> print(euclidian_distance)
1.359986705262199

尝试计算海拔高度不同的点之间的距离会导致 ValueError 异常。

geopy.distance.lonlat(x, y, z=0)

geopy.distance.distance 接受 (y, x)/(lat, lon) 格式的坐标，而其他一些库和系统可能使用 (x, y)/(lon, lat)。

此函数提供了一种便捷的方法，可以将 (x, y)/(lon, lat) 格式的坐标转换为 geopy.point.Point 实例。

示例

>>> from geopy.distance import lonlat, distance
>>> newport_ri_xy = (-71.312796, 41.49008)
>>> cleveland_oh_xy = (-81.695391, 41.499498)
>>> print(distance(lonlat(*newport_ri_xy), lonlat(*cleveland_oh_xy)).miles)
538.3904453677203
参数

  • x – 经度

  • y – 纬度

  • z – （可选）海拔高度

返回

Point(纬度，经度，海拔高度)

class geopy.distance.Distance(*args, **kwargs)

其他距离算法的基类。表示距离。

可用于单位转换。

>>> from geopy.distance import Distance
>>> Distance(miles=10).km
16.09344

Distance 实例具有来自 geopy.units 的所有 distance 属性，例如：km、m、meters、miles 等。

Distance 实例是不可变的。

它们支持比较。

>>> from geopy.distance import Distance
>>> Distance(kilometers=2) == Distance(meters=2000)
True
>>> Distance(kilometers=2) > Distance(miles=1)
True

字符串表示。

>>> from geopy.distance import Distance
>>> repr(Distance(kilometers=2))
'Distance(2.0)'
>>> str(Distance(kilometers=2))
'2.0 km'
>>> repr(Distance(miles=2))
'Distance(3.218688)'
>>> str(Distance(miles=2))
'3.218688 km'

算术运算。

>>> from geopy.distance import Distance
>>> -Distance(miles=2)
Distance(-3.218688)
>>> Distance(miles=2) + Distance(kilometers=1)
Distance(4.218688)
>>> Distance(miles=2) - Distance(kilometers=1)
Distance(2.218688)
>>> Distance(kilometers=6) * 5
Distance(30.0)
>>> Distance(kilometers=6) / 5
Distance(1.2)
__init__(*args, **kwargs)

有三种方法可以创建距离。

  • 从公里数。

    >>> from geopy.distance import Distance
>>> Distance(1.42)
Distance(1.42)

  • 从单位。

    >>> from geopy.distance import Distance
>>> Distance(kilometers=1.42)
Distance(1.42)
>>> Distance(miles=1)
Distance(1.609344)

  • 从点（仅针对非抽象距离），计算为所有点之间距离的总和。

    >>> from geopy.distance import geodesic
>>> geodesic((40, 160), (40.1, 160.1))
Distance(14.003702498106215)
>>> geodesic((40, 160), (40.1, 160.1), (40.2, 160.2))
Distance(27.999954644813478)
destination(point, bearing, distance=None)

使用起点、方位角和距离计算目的地。此方法仅适用于非抽象距离。

示例：一个距离 (34, 148) 向东 10 英里的点。

>>> import geopy.distance
>>> geopy.distance.distance(miles=10).destination((34, 148), bearing=90)
Point(33.99987666492774, 148.17419994321995, 0.0)
参数

  • point (geopy.point.Point，(latitude, longitude) 的列表或元组，或字符串，如 "%(latitude)s, %(longitude)s"。) – 起点。

  • bearing (float) – 方位角，以度为单位：0 – 北，90 – 东，180 – 南，270 或 -90 – 西。

  • distance (Distance) –

    距离，可以用于覆盖此实例。

    >>> from geopy.distance import distance, Distance
>>> distance(miles=10).destination((34, 148), bearing=90, distance=Distance(100))
Point(33.995238229104764, 149.08238904409637, 0.0)

返回类型

geopy.point.Point

class geopy.distance.geodesic(*args, **kwargs)

Bases: geopy.distance.Distance

计算点之间的测地线距离。

通过指定 ellipsoid 关键字参数来设置要使用的地球椭球模型。默认值为 ‘WGS-84’，这是全球最精确的模型。如果 ellipsoid 是一个字符串，则会在 ELLIPSOIDS 字典中查找它以获取长半轴、短半轴和扁率。否则，它应该是一个包含这些值的元组。有关详细信息，请参见 ELLIPSOIDS 字典上面的注释。

示例

>>> from geopy.distance import geodesic
>>> newport_ri = (41.49008, -71.312796)
>>> cleveland_oh = (41.499498, -81.695391)
>>> print(geodesic(newport_ri, cleveland_oh).miles)
538.390445368
class geopy.distance.great_circle(*args, **kwargs)

Bases: geopy.distance.Distance

使用球面几何来计算点之间的表面距离。

通过指定 radius 关键字参数来设置要使用的地球半径。它必须以公里为单位。默认值为使用模块常量 EARTH_RADIUS，它使用平均大圆半径。

示例

>>> from geopy.distance import great_circle
>>> newport_ri = (41.49008, -71.312796)
>>> cleveland_oh = (41.499498, -81.695391)
>>> print(great_circle(newport_ri, cleveland_oh).miles)
536.997990696

数据

class geopy.location.Location(address, point, raw)

包含解析后的地理编码器响应。可以将其迭代为 (location<String>, (latitude<float>, longitude<Float))。或者可以访问属性 address、latitude、longitude 或 raw。最后一个是地理编码器对此项响应的字典。

property address

位置，以地理编码器返回的格式化字符串或 geopy 构造的字符串表示，具体取决于服务。

返回类型

str

property altitude

位置的海拔高度。

注意

地理编码服务通常既不在请求中也不在响应中考虑海拔高度，因此几乎总是此属性的值为零。

返回类型

float

property latitude

位置的纬度。

返回类型

float

property longitude

位置的经度。

返回类型

float

property point

geopy.point.Point 实例，表示位置的纬度、经度和海拔高度。

返回类型

geopy.point.Point

property raw

位置的原始、未解析的地理编码器响应。有关详细信息，请参阅服务的文档。

返回类型

dict

class geopy.point.Point(latitude=None, longitude=None, altitude=None)

具有纬度、经度和海拔高度的测地线点。

纬度和经度是以度为单位的浮点值。海拔高度是以公里为单位的浮点值。参考水平面不予考虑，因此取决于应用程序，请保持一致！所有值的默认值为 0。

可以使用多种方法创建点……

使用纬度、经度和海拔高度

>>> p1 = Point(41.5, -81, 0)
>>> p2 = Point(latitude=41.5, longitude=-81)

使用 2 到 3 个值的序列（纬度、经度、海拔高度）

>>> p1 = Point([41.5, -81, 0])
>>> p2 = Point((41.5, -81))

复制另一个 Point 实例

>>> p2 = Point(p1)
>>> p2 == p1
True
>>> p2 is p1
False

提供包含至少纬度和经度的字符串

>>> p = Point('41.5,-81.0')
>>> p = Point('+41.5 -81.0')
>>> p = Point('41.5 N -81.0 W')
>>> p = Point('-41.5 S, 81.0 E, 2.5km')
>>> p = Point('23 26m 22s N 23 27m 30s E 21.0mi')
>>> p = Point('''3 26' 22" N 23 27' 30" E''')

可以通过名称或索引访问 Point 值

>>> p = Point(41.5, -81.0, 0)
>>> p.latitude == p[0]
True
>>> p.longitude == p[1]
True
>>> p.altitude == p[2]
True

解包（或迭代）时，将返回一个 (latitude, longitude, altitude) 元组

>>> latitude, longitude, altitude = p

文本表示

>>> p = Point(41.5, -81.0, 12.3)
>>> str(p)  # same as `p.format()`
'41 30m 0s N, 81 0m 0s W, 12.3km'
>>> p.format_unicode()
'41° 30′ 0″ N, 81° 0′ 0″ W, 12.3km'
>>> repr(p)
'Point(41.5, -81.0, 12.3)'
>>> repr(tuple(p))
'(41.5, -81.0, 12.3)'
static __new__(cls, latitude=None, longitude=None, altitude=None)
参数

  • latitude (float) – 纬度。

  • longitude (float) – 经度。

  • altitude (float) – 海拔高度。

format(altitude=None, deg_char='', min_char='m', sec_char='s')

将十进制度数 (DD) 格式化为度分秒 (DMS)。

>>> p = Point(41.5, -81.0, 12.3)
>>> p.format()
'41 30m 0s N, 81 0m 0s W, 12.3km'
>>> p = Point(41.5, 0, 0)
>>> p.format()
'41 30m 0s N, 0 0m 0s E'

另请参阅 format_unicode()。

参数

altitude (bool) – 是否包含 altitude 值。默认情况下，如果它非零，则会自动包含在内。

format_altitude(unit='km')

使用单位格式化海拔高度。

>>> p = Point(41.5, -81.0, 12.3)
>>> p.format_altitude()
'12.3km'
>>> p = Point(41.5, -81.0, 0)
>>> p.format_altitude()
'0.0km'
参数

unit (str) – 结果海拔高度单位。支持的单位在 from_string() 文档中列出。

format_decimal(altitude=None)

使用海拔高度格式化十进制度数。

>>> p = Point(41.5, -81.0, 12.3)
>>> p.format_decimal()
'41.5, -81.0, 12.3km'
>>> p = Point(41.5, 0, 0)
>>> p.format_decimal()
'41.5, 0.0'
参数

altitude (bool) – 是否包含 altitude 值。默认情况下，如果它非零，则会自动包含在内。

format_unicode(altitude=None)

format() 使用度、分和秒的漂亮 Unicode 字符。

>>> p = Point(41.5, -81.0, 12.3)
>>> p.format_unicode()
'41° 30′ 0″ N, 81° 0′ 0″ W, 12.3km'
参数

altitude (bool) – 是否包含 altitude 值。默认情况下，如果它非零，则会自动包含在内。

classmethod from_point(point)

从另一个 Point 实例创建并返回一个新的 Point 实例。

classmethod from_sequence(seq)

从任何包含 2 到 3 个元素的可迭代对象创建并返回一个新的 Point 实例。如果存在，这些元素必须分别是纬度、经度和海拔高度。

classmethod from_string(string)

从包含纬度和经度以及可选海拔高度的字符串创建并返回一个 Point 实例。

纬度和经度必须以度为单位，可以是十进制形式，也可以表示弧分和弧秒（用 Unicode 撇号和双撇号、ASCII 引号和双引号或“m”和“s”标记）。度符号是可选的，可以在小数点后（在十进制形式中）和弧分和弧秒之前包含。从南和西给出的坐标（用 S 和 W 后缀表示）将通过改变符号转换为北和东。如果没有（或部分）方向指示，则假设为北和东。纬度和经度必须至少用空格、逗号或分号（每个都带有可选的周围空格）分隔。

如果提供海拔高度，则它必须是带给定单位的十进制数。支持以下单位缩写（不区分大小写）

  • km (公里)

  • m (米)

  • mi (英里)

  • ft (英尺)

  • nm, nmi (海里)

一些可以工作的示例字符串包括

  • 41.5;-81.0

  • 41.5,-81.0

  • 41.5 -81.0

  • 41.5 N -81.0 W

  • -41.5 S;81.0 E

  • 23 26m 22s N 23 27m 30s E

  • 23 26' 22" N 23 27' 30" E

  • UT: N 39°20' 0'' / W 74°35' 0''

classmethod parse_altitude(distance, unit)

解析海拔高度，管理单位转换。

>>> Point.parse_altitude(712, 'm')
0.712
>>> Point.parse_altitude(712, 'km')
712.0
>>> Point.parse_altitude(712, 'mi')
1145.852928
参数

  • distance (float) – 海拔高度的数值。

  • unit (str) – distance 单位。支持的单位在 from_string() 文档中列出。

classmethod parse_degrees(degrees, arcminutes, arcseconds, direction=None)

将度、分、秒和方向 (N、S、E、W) 转换为单个度数。

返回类型

float

class geopy.timezone.Timezone(pytz_timezone, raw)

包含对时区请求的解析响应，该请求在少数提供此类查找的地理编码器中实现。

property pytz_timezone

pytz 时区实例。

返回类型

pytz.tzinfo.BaseTzInfo

property raw

时区的原始、未解析的地理编码器响应。有关详细信息，请参阅该服务的文档。

返回类型

dict

单位转换

geopy.units 模块提供用于执行角度和距离单位转换的实用程序函数。

为了方便起见，提供了一些简短的别名（例如，km() 是 kilometers() 的别名）。

geopy.units.arcmin(degrees=0, radians=0, arcseconds=0)

将角度转换为弧分。

geopy.units.arcminutes(degrees=0, radians=0, arcseconds=0)

将角度转换为弧分。

geopy.units.arcsec(degrees=0, radians=0, arcminutes=0)

将角度转换为弧秒。

geopy.units.arcseconds(degrees=0, radians=0, arcminutes=0)

将角度转换为弧秒。

geopy.units.degrees(radians=0, arcminutes=0, arcseconds=0)

将角度转换为度数。

geopy.units.feet(kilometers=0, meters=0, miles=0, nautical=0)

将距离转换为英尺。

geopy.units.ft(kilometers=0, meters=0, miles=0, nautical=0)

将距离转换为英尺。

geopy.units.kilometers(meters=0, miles=0, feet=0, nautical=0)

将距离转换为公里。

geopy.units.km(meters=0, miles=0, feet=0, nautical=0)

将距离转换为公里。

geopy.units.m(kilometers=0, miles=0, feet=0, nautical=0)

将距离转换为米。

geopy.units.meters(kilometers=0, miles=0, feet=0, nautical=0)

将距离转换为米。

geopy.units.mi(kilometers=0, meters=0, feet=0, nautical=0)

将距离转换为英里。

geopy.units.miles(kilometers=0, meters=0, feet=0, nautical=0)

将距离转换为英里。

geopy.units.nautical(kilometers=0, meters=0, miles=0, feet=0)

将距离转换为海里。

geopy.units.nm(kilometers=0, meters=0, miles=0, feet=0)

将距离转换为海里。

geopy.units.rad(degrees=0, arcminutes=0, arcseconds=0)

将角度转换为弧度。

geopy.units.radians(degrees=0, arcminutes=0, arcseconds=0)

将角度转换为弧度。

异常

class geopy.exc.GeopyError

Bases: Exception

Geopy 特定的异常都继承自 GeopyError。

class geopy.exc.ConfigurationError

Bases: geopy.exc.GeopyError, ValueError

当实例化地理编码器时，给定的参数无效。有关更多详细信息，请参阅每个地理编码器 __init__ 的文档。

class geopy.exc.GeocoderServiceError

Bases: geopy.exc.GeopyError

调用远程地理编码服务时发生异常，并且 geopy 无法引发更具体的异常。当调用地理编码器的 geocode 或 reverse 方法时，这是可能引发的最通用的异常，任何非 geopy 异常都将被捕获并转换为此异常。异常消息将是原始异常的消息。

class geopy.exc.GeocoderQueryError

基类：geopy.exc.GeocoderServiceError，ValueError

Geopy 发现输入会导致请求失败，或者请求已发出，但远程地理编码服务响应请求无效。

class geopy.exc.GeocoderQuotaExceeded

基类：geopy.exc.GeocoderServiceError

远程地理编码服务拒绝履行请求，因为客户端已使用其配额。

class geopy.exc.GeocoderRateLimited(message, *, retry_after=None)

基类：geopy.exc.GeocoderQuotaExceeded，OSError

远程地理编码服务已对请求进行限速。稍后再试可能会有所帮助。

这种类型的异常有一个retry_after属性，它包含服务要求等待的时间量（以秒为单位）。如果响应中没有此类数据，则可能是None。

版本 2.2 新增功能。

class geopy.exc.GeocoderAuthenticationFailure

基类：geopy.exc.GeocoderServiceError

远程地理编码服务拒绝了用于实例化此地理编码器的 API 密钥或帐户凭据。

class geopy.exc.GeocoderInsufficientPrivileges

基类：geopy.exc.GeocoderServiceError

远程地理编码服务拒绝使用提供的帐户凭据来履行请求。

class geopy.exc.GeocoderTimedOut

基类：geopy.exc.GeocoderServiceError，TimeoutError

对地理编码服务的调用已中止，因为在地理编码类或（如果指定）方法调用的timeout参数范围内未收到响应。某些服务始终速度很慢，可能需要更高的超时才能使用它们。

class geopy.exc.GeocoderUnavailable

基类：geopy.exc.GeocoderServiceError，OSError

无法建立与远程地理编码服务的连接，或者服务响应了一个代码，表明它不可用。

class geopy.exc.GeocoderParseError

基类：geopy.exc.GeocoderServiceError

Geopy 无法解析服务的响应。这可能是由于 geopy 中的错误所致。

class geopy.exc.GeocoderNotFound

Bases: geopy.exc.GeopyError, ValueError

调用者请求与字符串匹配的地理编码器，例如，"google" > GoogleV3，但找不到任何地理编码器。

适配器

适配器是地理编码器使用的 HTTP 客户端实现。

一些适配器可能支持保持活动连接、请求重试、http2、Cookie 持久性、响应压缩等等。

适配器应被视为实现细节。大多数情况下，您无需了解它们的存在，除非您要调整 HTTP 客户端设置。

版本 2.0 中的新增功能： 适配器目前在暂行基础上提供。

支持的适配器

class geopy.adapters.RequestsAdapter(*, proxies, ssl_context, pool_connections=10, pool_maxsize=10, max_retries=2, pool_block=False)

基类：geopy.adapters.BaseSyncAdapter

使用requests库的适配器。

requests支持保持活动连接、重试、持久化 Cookie、允许响应压缩并使用 HTTP/1.1 [目前]。

为了使用此适配器，必须安装requests包。

requests 的trust_env值设置为 false，这意味着环境不会影响 requests 的配置。可以使用ssl_context和proxies设置进行配置。

版本 2.4 中的变更： 此适配器以前默认使用certifi CA 捆绑包，如果未显式提供ssl_context。这已更改为默认使用系统 CA 存储。

class geopy.adapters.URLLibAdapter(*, proxies, ssl_context)

基类：geopy.adapters.BaseSyncAdapter

使用 Python 标准库中的 urllib 的后备适配器，请参见urllib.request.urlopen()。

urllib 不支持保持活动连接、请求重试，不持久化 Cookie 并且仅限于 HTTP/1.1。

urllib 是 geopy 1.x 中唯一可用的请求选项，因此此适配器在 HTTP 请求方面与 geopy 1.x 的行为相同。

class geopy.adapters.AioHTTPAdapter(*, proxies, ssl_context)

基类：geopy.adapters.BaseAsyncAdapter

使用aiohttp库的适配器。

aiohttp支持保持活动连接、持久化 Cookie、允许响应压缩并使用 HTTP/1.1 [目前]。

为了使用此适配器，必须安装aiohttp包。

基类

class geopy.adapters.AdapterHTTPError(message, *, status_code, headers, text)

基类：OSError

适配器在收到具有非成功状态代码的 HTTP 响应时必须引发的异常。

基地理编码器类将此异常转换为geopy.exc.GeocoderServiceError的实例。

__init__(message, *, status_code, headers, text)
参数

  • message (str) – 标准异常消息。

  • status_code (int) – HTTP 状态码。

  • headers (dict) –

    HTTP 响应读取器。一个带小写或不区分大小写键的映射对象。

    版本 2.2 新增功能。

  • text (str) – HTTP 主体文本。

class geopy.adapters.BaseAdapter(*, proxies, ssl_context)

适配器基类。

有两种类型的适配器

具体的适配器实现必须扩展上述两个基适配器之一。

有关如何指定地理编码器使用的适配器的详细信息，请参见 geopy.geocoders.options.default_adapter_factory。

__init__(*, proxies, ssl_context)

初始化适配器。

参数
abstract get_json(url, *, timeout, headers)

与 get_text 相同，只是响应预期是一个有效的 JSON。返回值是解析后的 JSON。

如果响应无法解析，则必须引发 geopy.exc.GeocoderParseError。

参数
abstract get_text(url, *, timeout, headers)

执行 GET 请求并以字符串形式返回响应。

此方法不应引发除以下异常之外的任何异常

参数
class geopy.adapters.BaseSyncAdapter(*, proxies, ssl_context)

Bases: geopy.adapters.BaseAdapter

同步适配器的基类。

class geopy.adapters.BaseAsyncAdapter(*, proxies, ssl_context)

Bases: geopy.adapters.BaseAdapter

异步适配器的基类。

另请参见：异步模式。

日志记录

geopy 将使用日志记录器名称 geopy 在级别 DEBUG 上记录地理编码 URL，对于某些地理编码器，这些 URL 将包含身份验证信息。

具有不成功状态码的响应的 HTTP 主体将以 INFO 级别记录。

默认日志记录级别为 NOTSET，它将消息处理委托给根日志记录器。有关更多信息，请参见 logging.Logger.setLevel() 文档。

语义版本控制

geopy 尝试遵循语义版本控制，但一些重大更改仍在次要版本中进行，例如

  • 未记录的 API 的向后不兼容的更改。这不会影响任何人，除非他们扩展地理编码器类或使用未记录的功能或修补任何东西。如果您认为 geopy 中缺少某些内容，请考虑打开一个问题或提供补丁/PR，而不是在 geopy 周围进行黑客攻击。

  • 地理编码服务有时会引入新的 API 并弃用以前的 API。我们尝试在不破坏地理编码器 API 接口的情况下进行升级，但 geopy.location.Location.raw 值可能会以向后不兼容的方式更改。

  • 对无效输入和特殊边缘情况的行为可能会发生更改。例如，geopy.point.Point 实例以前会进行坐标值规范化，尽管没有记录，并且对于 [-90; 90] 范围之外的纬度，它是完全错误的。因此，现在会抛出 ValueError 异常，而不是使用纬度的错误规范化值（#294）。

正在逐步淘汰的功能和用法尽可能使用弃用 warnings。确保使用 -Wd 开关运行您的 python，以查看您的代码是否发出警告。

为了使升级不那么痛苦，请在升级之前阅读更改日志。

更改日志

2.x.x 系列的更改日志.

1.x.x 系列的更改日志.

0.9x 系列的更改日志.