使用Geocoder gem调用Nominatim API时返回无效JSON报错

问题描述 #

• 使用Geocoder gem 1.8版本，运行环境为Rails 7.1.3.2 + Ruby 3.2.2
• 在Rails控制台执行Geocoder.search('Paris')时，返回错误提示：

  Geocoding API's response was not valid JSON
  => []
  

• 多个项目测试结果一致，此前功能正常，Geocoder配置文件为空
• 开启调试日志后发现，实际返回的是Nominatim的访问封禁页面，核心原因是违反了其使用政策，要求必须设置自定义HTTP Referrer或User-Agent标识应用，同时避免大规模批量请求

解决方案 #

1. 配置自定义请求标识 #

在Rails项目的config/initializers/geocoder.rb中添加配置（文件不存在则新建），设置合法的User-Agent：

Geocoder.configure(
  http_headers: {
    "User-Agent" => "你的应用名称/版本号 (联系邮箱)"
  }
)

示例配置：

Geocoder.configure(
  http_headers: {
    "User-Agent" => "MyStoreApp/2.1.0 (dev@mystore.com)"
  }
)

2. 合规控制请求频率 #

• 严格遵守Nominatim的请求频率限制，非商业用户建议控制在1次/秒以内
• 如需批量地理编码，优先使用本地缓存，或考虑部署私有Nominatim实例

3. 申请解除封禁（若已被限制） #

如果配置标识后仍无法访问，可发送邮件至nominatim@openstreetmap.org，说明应用情况及已调整的配置，申请解除封禁

内容的提问来源于stack exchange，提问作者Annabelle White