photon

photon 是一个为 OpenStreetMap 数据构建的开源地理编码器。它基于 elasticsearch - 一个高效、强大且高度可扩展的搜索平台。

photon 由 komoot 发起，提供即时搜索和多语言支持。在 photon.komoot.io 可以找到我们的公共 API 和演示。在 2020 年 10 月之前，API 可通过 photon.komoot.de 访问。请相应更新您的应用程序。

贡献

欢迎所有代码贡献和错误报告！

如有问题，请发送邮件至我们的邮件列表。

欢迎测试和参与！

许可证

photon 软件是开源的，根据 Apache License, Version 2.0 许可。

特性

高性能
高度可扩展
即时搜索
多语言搜索
位置偏好
容错输入
按 osm 标签和值过滤
按边界框过滤
将坐标反向地理编码为地址
OSM 数据导入（基于 Nominatim）包括持续更新

安装

photon 需要 Java，至少 11 版本。

下载搜索索引（截至 2023-10-26，压缩后 72G GB，解压后 159GB，全球覆盖，语言：英语、德语、法语和本地名称）。搜索索引每周更新，由 GraphHopper 在 lonvia 的支持下提供。现在从发布页面获取最新版本的 photon。

确保已安装 bzip2 或 pbzip2，并在 shell 中执行以下两个命令之一。这将一步完成下载、解压和提取大型数据库：

wget -O - https://download1.graphhopper.com/public/photon-db-latest.tar.bz2 | bzip2 -cd | tar x
# 使用 pbzip2 可以显著加快提取速度（推荐）：
wget -O - https://download1.graphhopper.com/public/photon-db-latest.tar.bz2 | pbzip2 -cd | tar x

构建

photon 使用 gradle 进行构建。要从源代码构建软件包，请确保已安装 JDK。然后运行：

./gradlew app:es_embedded:build

这将构建并测试 photon。最终的 jar 文件可以在 target 目录中找到。

实验性 OpenSearch 版本

该仓库还包含一个可在最新版本的 OpenSearch 上运行的版本。这个版本仍处于实验阶段。要构建 OpenSearch 版本，请运行：

./gradlew app:opensearch:build

最终的 jar 文件可以在 target/photon-opensearch-<VERSION>.jar 中找到。

此版本生成的索引与 ElasticSearch 版本不兼容。目前没有预构建的索引可用。您需要从 Nominatim 数据库创建自己的导出。详见下文"自定义搜索数据"。

使用

使用以下命令启动 photon：

java -jar photon-*.jar

如果 photon_data 目录不在默认位置 ./photon_data，请使用 -data-dir 选项指向 photon_data 的父目录。在向 photon 发送请求之前，ElasticSearch 需要将一些数据加载到内存中，因此请耐心等待几秒钟。

检查 URL http://localhost:2322/api?q=berlin 以确认 photon 是否正常运行。您可能想使用我们的 leaflet 插件在地图上查看结果。

要启用 CORS（跨站点请求），使用 -cors-any 允许任何来源，或使用 -cors-origin 并指定特定来源作为参数。默认情况下，CORS 支持是禁用的。

通过运行 java -jar photon-*.jar -h 了解更多 photon 的功能。可用选项如下：

-h                    显示帮助/用法

-cluster              将服务器放入的 elasticsearch 集群名称（默认为 'photon'）

-transport-addresses  外部 elasticsearch 节点的逗号分隔地址，客户端可以连接到这些地址（默认为空字符串，强制启动内部节点）

-nominatim-import     将 nominatim 数据库导入 photon（这将删除先前的索引）

-nominatim-update     从 nominatim 数据库获取更新到 photon 并退出（仅更新索引，不提供 API）

-languages            nominatim 导入器应导入和在运行时使用的语言，逗号分隔（默认为 'en,fr,de,it'）

-default-language     当用户未明确选择语言时返回结果的默认语言

-country-codes        nominatim 导入器应导入的国家代码过滤器，逗号分隔。如果为空，则处理整个地球

-extra-tags           为每个地点保存的其他标签的逗号分隔列表

-synonym-file         包含同义词和分类术语的文件

-json                 导入 nominatim 数据库并将其转储为类似 json 的文件（对开发有用）

-host                 Postgres 主机（默认 127.0.0.1）

-port                 Postgres 端口（默认 5432）

-database             Postgres 数据库（默认 nominatim）

-user                 Postgres 用户（默认 nominatim）

-password Postgres 密码（默认为空）

-data-dir 数据目录（默认为 '.'）

-listen-port 监听端口（默认为 2322）

-listen-ip 监听地址（默认为 '0.0.0.0'）

-cors-any 为任何来源启用跨站资源共享（默认不支持 CORS）

-cors-origin 为指定的来源启用跨站资源共享，以逗号分隔（默认不支持 CORS）

-enable-update-api 启用额外的 /nominatim-update 端点，允许从 nominatim 数据库触发更新

自定义搜索数据

如果你需要其他语言的搜索数据或限制在某个国家的数据，你需要自己创建搜索数据。一旦你的 Nominatim 数据库准备就绪，你就可以将数据导入到 photon。

如果你还没有为 Nominatim 数据库用户设置密码，现在就设置（根据需要更改用户名和密码）：

su postgres
psql
ALTER USER nominatim WITH ENCRYPTED PASSWORD 'mysecretpassword';

将数据导入到 photon：

java -jar photon-*.jar -nominatim-import -host localhost -port 5432 -database nominatim -user nominatim -password mysecretpassword -languages es,fr

导入全球数据集将需要几小时/几天时间，建议使用 SSD/NVME 硬盘来加速 Nominatim 查询。

通过 Nominatim 从 OSM 更新

要从 Nominatim 更新现有的 Photon 数据库，首先需要用适当的触发器准备 Nominatim 数据库：

java -jar photon-*.jar -database nominatim -user nominatim -password ... -nominatim-update-init-for update_user

此脚本必须使用具有创建表、函数和触发器权限的用户运行。

'update-user' 是更新 Photon 数据库时将使用的 PostgreSQL 用户。该用户需要对数据库的读取权限。必要的更新权限将在初始化过程中授予。

现在你可以使用文档中描述的常规方法在 Nominatim 上运行更新。要使 Photon 数据库保持最新，停止 Nominatim 更新，然后运行 Photon 更新进程：

java -jar photon-*.jar -database nominatim -user nominatim -password ... -nominatim-update

你也可以启用更新 API 来运行 photon 进程：

java -jar photon-*.jar -enable-update-api -database nominatim -user nominatim -password ...

然后你可以这样触发更新：

curl http://localhost:2322/nominatim-update

这只会启动更新。要检查更新是否完成，使用状态 API：

curl http://localhost:2322/nominatim-update/status

当更新正在进行时，它会返回一个单一的 JSON 字符串 "BUSY"，当可以开始另一轮更新时，返回 "OK"。

为了方便起见，这个仓库包含了一个脚本，可以使用 Photon 的更新 API 持续更新 Nominatim 和 Photon。确保你已经用 -enable-update-api 启动了 Photon，然后运行：

export NOMINATIM_DIR=/srv/nominatim/...
./continuously_update_from_nominatim.sh

其中 NOMINATIM_DIR 是你的 Nominatim 安装的项目目录。

搜索 API

搜索

http://localhost:2322/api?q=berlin

带位置偏好的搜索

http://localhost:2322/api?q=berlin&lon=10&lat=52

有两个可选参数可以影响位置偏好。'zoom' 描述了围绕中心点的半径范围。这是一个应该大致对应于相应地图的缩放参数的数字。默认值是 zoom=16。

location_bias_scale 描述了结果的重要性应该被考虑的程度。合理的值从 0.0（几乎完全忽略重要性）到 1.0（重要性有大约相同的影响）。默认值是 0.2。

http://localhost:2322/api?q=berlin&lon=10&lat=52&zoom=12&location_bias_scale=0.1

反向地理编码坐标

http://localhost:2322/reverse?lon=10&lat=52

可以使用可选的半径参数来指定反向地理编码的范围（以公里为单位）。该值必须大于 0 且小于 5000。

http://localhost:2322/reverse?lon=10&lat=52&radius=10

调整结果数量

http://localhost:2322/api?q=berlin&limit=2

调整语言

http://localhost:2322/api?q=berlin&lang=it

如果省略，将使用 'accept-language' HTTP 头（浏览器默认设置）。如果两者都未设置，将返回地点的本地名称。在 OpenStreetMap 数据中，通常是 name 标签的值，例如东京的本地名称是東京都。

通过边界框过滤结果

预期格式为 minLon,minLat,maxLon,maxLat。

http://localhost:2322/api?q=berlin&bbox=9.5,51.5,11.5,53.5

通过标签和值过滤结果

注意：过滤器仅适用于主要OSM标签，并非所有OSM标签/值组合都可搜索。实际列表取决于Nominatim数据库使用的导入样式（例如settings/import-full.style）。所有带有"main"属性的标签/值组合都包含在photon数据库中。

如果存在一个或多个名为osm_tag的查询参数，photon将尝试按这些标签过滤结果。通常，osm_tag请求参数值的预期格式（语法）如下：

包含带标签的地点：osm_tag=key:value
排除带标签的地点：osm_tag=!key:value
包含带标签键的地点：osm_tag=key
包含带标签值的地点：osm_tag=:value
排除带标签键的地点：osm_tag=!key
排除带标签值的地点：osm_tag=:!value

例如，要搜索所有名为berlin且标签为tourism=museum的地点，应构造如下URL：

http://localhost:2322/api?q=berlin&osm_tag=tourism:museum

或仅按键搜索：

http://localhost:2322/api?q=berlin&osm_tag=tourism

您还可以将此功能用于反向地理编码。想查看距离某个位置最近的5家药店吗？

http://localhost:2322/reverse?lon=10&lat=52&osm_tag=amenity:pharmacy&limit=5

按图层过滤结果

可用图层列表：

house（房屋）
street（街道）
locality（地方）
district（区）
city（城市）
county（县）
state（州）
country（国家）
other（其他，如自然特征）

http://localhost:2322/api?q=berlin&layer=city&layer=locality

上面的示例将返回城市和地方。

GeoJSON格式的结果

{
  "features": [
    {
      "properties": {
        "name": "Berlin",
        "state": "Berlin",
        "country": "Germany",
        "countrycode": "DE",
        "osm_key": "place",
        "osm_value": "city",
        "osm_type": "N",
        "osm_id": 240109189
      },
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.3888599, 52.5170365]
      }
    },
    {
      "properties": {
        "name": "Berlin Olympic Stadium",
        "street": "Olympischer Platz",
        "housenumber": "3",
        "postcode": "14053",
        "state": "Berlin",
        "country": "Germany",
        "countrycode": "DE",
        "osm_key": "leisure",
        "osm_value": "stadium",
        "osm_type": "W",
        "osm_id": 38862723,
        "extent": [13.23727, 52.5157151, 13.241757, 52.5135972]
      },
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.239514674078611, 52.51467945]
      }
    }
  ]
}