常用文档转换API汇总
使用NodeJS开始Geo API服务
2024-10-10
你有没有想过像Uber这样的应用程序是如何确切地知道你的位置的？他们使用一种称为地理编码的过程，可以将地址转换为地图坐标。Positionstack 是一个使地理编码变得简单的 API。
这篇博客将向您介绍positionstack以及它为什么如此有用。它涵盖了全球超过20亿个地点。我们还将讨论它的一些功能，比如批量地理编码和对多种语言的支持，这些功能让它在开发者中非常受欢迎。
您将学习如何使用positionstack API，并通过简单的示例来查找位置和地址。我们将向您展示如何使用Node.js（一种编程语言）来实现这一过程。
在这篇博客的结尾，您会知道为什么 Positionstack 是一个强大的工具，任何想要为他们的应用程序添加位置功能的人都可以受益。
什么是 positionstack，是什么让它强大？
positionstack 是一种 API 服务，它提供了简单可靠的正向和反向地理编码解决方案。该服务覆盖全球超过 20 亿个地点和地址。
Positionstack API 的功能包括批量地理编码、多语言支持以及可嵌入地图 URL 等。您可以选择 JSON、XML 或特定于地理编码的 GeoJSON 格式来获取地理位置 API 的结果。API 的平均响应时间在 10 毫秒到 100 毫秒之间，具体取决于您的请求大小。
- 正向地理编码
- 反向地理编码
- 批量请求
- 可嵌入地图
- JSON，XML 和 GeoJSON
- 多种语言
positionstack 已成为许多企业的 Go to Geolocation API。以下是 Positionstack 用户每天请求 1+ 亿次地理编码 API 查找的原因：
- 覆盖全球超过20亿个地址！
- 实时地理编码：对任何全球地址或坐标集进行实时地理编码，并查找位置组件、国家/地区和时区数据等等。
- 可扩展的基础设施：apilayer 云基础设施支持 Positionstack，使其能够处理数十亿个地理编码请求，响应时间在 10 到 100 毫秒之间。
- 全球覆盖范围：充分利用来自高质量数据供应商的大量全球地理编码数据，每天多次更新。
- 公平定价：您每月免费获得10，000个地理编码请求。如果您需要更多，高级地理编码订阅每月仅需9.99美元。
apilayer是一家奥地利技术公司，构建了各种可靠的编程接口（API），它构建并维护了positionstack API。apilayer为开发人员和初创公司提供价格合理的尖端API。
简而言之，positionstack是市场上最先进、最轻量级、最经济实惠、最易于使用的地理编码解决方案。本文详细介绍了它的各种API端点、可用选项以及Node.js和其他平台（Postman和RAD Studio REST插件）的教程。
如何访问positionstack API？
首先获取您的API凭据，并设置您的订阅计划：
您可以通过此仪表板监控您的使用情况。
API访问密钥和身份验证
接下来，要检查是否一切正常，只需在您最喜欢的Web浏览器中运行此URL：
http://api.positionstack.com/v1/forward?access_key=YOUR_ACCESS_KEY&query=1600%20Pennsylvania%20Ave%20NW,%20Washington%20DC您应该在浏览器中看到此API响应：
API错误
如果您的API请求失败，API将返回一个错误对象。它包含子对象代码和指示所发生错误类型的消息。
以下是最常见的API错误：
| 代码 | 类型 | 描述 |
| 401 | 无效访问键 | 提供了无效的API访问密钥。 |
| 401 | 丢失存取键 | 未提供API访问密钥。 |
| 401 | 非活动用户 | 给定的用户帐户处于非活动状态。 |
| 403 | https_access_restricted | 当前订阅计划不支持HTTPS访问。 |
| 403 | 函数访问受限 | 当前订阅计划不支持给定的API终结点。 |
| 404 | 无效的_API_函数 | 给定的API终结点不存在。 |
| 404 | 404_not_found | 页面没有找到 |
| 429 | 已达到使用限制 | 给定的用户帐户已达到其每月允许的请求量。 |
| 429 | 达到速率极限 | 给定的用户帐户已达到速率限制。 |
| 500 | 内部错误 | 发生内部错误。 |
哪些正向地理编码端点可通过 API 获得？
正向地理编码是将自由文本地址或地点转换为位置数据的过程。要发出正向地理编码请求，请使用API的正向端点并使用查询参数指定查询。
以下是HTTP GET请求参数：
| 对象 | 描述 |
| 访问密钥 | [必需]您的API访问密钥，可在您的帐户仪表板中找到。 |
| 查询 | [必需]将您的查询指定为自由文本地址、地名或使用任何其他常见的基于文本的位置标识符（例如邮政编码、城市名称、地区名称）。 |
| 国家 | [可选]通过一个或多个逗号分隔的2字母（例如Au）或3字母国家代码（例如AUS）过滤地理编码结果。示例：country=Au，CA，按澳大利亚和加拿大筛选。下载：支持的国家（CSV） |
| 区域 | [可选]通过指定区域过滤地理编码结果。这可以是一个街区、地区、市、县、州或行政区域。例如：region=柏林，按柏林的位置进行过滤。 |
| 语言 | [可选]通过指定首选语言的2个字母（例如en）或3个字母代码（例如eng）来翻译特定的API响应对象。（默认：英文） |
| 国家模块 | [可选]设置为1以使国家/地区模块能够在您的API响应中包括更广泛的国家/地区数据。在国家模块部分阅读更多相关信息。 |
| 太阳模块 | [可选]设置为1，使Sun模块能够在您的API响应中包括占星数据。在Sun模块部分中阅读有关此的更多信息。 |
| 时区模块 | [可选]设置为1以使时区模块能够在API响应中包括时区数据。在时区模块部分阅读更多关于此的信息。 |
| bbox模块 | [可选]设置为1以使边界框模块能够在API响应中包括边界坐标。在边界框模块部分中了解更多信息。 |
| 限制 | [可选]指定1到80之间的限制，以限制每个地理编码查询返回的结果数。批处理请求可以包含多个地理编码查询。（默认值：10个结果） |
| 领域 | [可选]指定一个或多个响应字段以减小API响应大小。了解如何在指定响应字段部分中使用此选项。 |
| 输出 | [可选]指定首选的API输出格式。可用值：JSON（默认）、XML和GeoJSON。 |
| 回调 | [可选]使用此参数指定要将API响应包装在其中的JSONP回调函数名称。了解有关JSONP回调的更多信息。 |
每个API响应由18个不同的响应对象组成：
| 响应对象 | 描述 |
| 数据 | 返回两个大的数据数组：请求和结果，下面将详细解释。 |
| 结果 | 返回此API请求的位置结果数组。子数组的数量直接取决于指定的限制值。下面列出了所有子阵列和子对象。 |
| 结果>纬度 | 返回与定位结果关联的纬度坐标。 |
| 结果>经度 | 返回与定位结果关联的经度坐标。 |
| 结果>标签 | 返回格式化的地名或地址。 |
| 结果>名称 | 返回定位结果的名称。这可能是一个地名、地址、邮政编码等等。 |
| 结果>类型 | 返回定位结果的类型。以下是所有可用的位置类型列表：地点，地址，街道，邻里，自治市，localadmin，地方，县，宏观国家，地区，宏观地区，国家，粗略，邮政编码。 |
| 结果>数量 | 返回与定位结果关联的街道或门牌号。 |
| 结果>街道 | 返回与定位结果关联的街道名称。 |
| 搜索结果>邮政编码 | 返回与位置结果关联的邮政编码或邮政编码。 |
| 结果>信心 | 返回与位置结果关联的介于0（0%置信度）和1（100%置信度）之间的置信度分数。 |
| 结果>区域 | 返回与定位结果关联的区域的名称。 |
| 结果>区域代码 | 返回与定位结果关联的区域代码。 |
| 结果>行政区域 | 返回与定位结果关联的行政区域的名称。 |
| 结果>邻域 | 返回与定位结果关联的邻域的名称。 |
| 结果>国家 | 返回与定位结果关联的国家/地区的通用名称。 |
| 结果>国家代码 | 返回与位置结果关联的国家/地区的ISO 3166 Alpha 2（两个字母）代码。 |
| 结果> map_url | 返回与定位结果关联的可嵌入映射。 |
通过API可以使用哪些反向地理编码端点？
反向地理编码是将坐标（纬度/经度）或IP地址转换为位置数据的过程。要发出反向地理编码请求，请使用API的反向端点，并使用查询参数指定查询。
HTTP GET请求参数
以下是HTTP GET请求参数：
| 对象 | 描述 |
| 访问密钥 | [必需]您的API访问密钥，可在您的帐户仪表板中找到。 |
| 查询 | [必需]以纬度、经度格式将您的查询指定为坐标（例如，查询=40.7638435，-73.9729691）或使用IP地址进行自动坐标检测（例如，查询=72.229.28.185）。 |
| 国家 | [可选]通过一个或多个逗号分隔的2字母（例如Au）或3字母国家代码（例如AUS）过滤地理编码结果。示例：country=Au，CA，按澳大利亚和加拿大筛选。下载：支持的国家（CSV） |
| 区域 | [可选]通过指定区域过滤地理编码结果。这可以是一个街区、地区、市、县、州或行政区域。例如：region=柏林，按柏林的位置进行过滤。 |
| 语言 | [可选]通过指定首选语言的2个字母（例如en）或3个字母代码（例如eng）来翻译特定的API响应对象。（默认：英文） |
| 国家模块 | [可选]设置为1以使国家/地区模块能够在您的API响应中包括更广泛的国家/地区数据。在国家模块部分阅读更多相关信息。 |
| 太阳模块 | [可选]设置为1，使Sun模块能够在您的API响应中包括占星数据。在Sun模块部分中阅读有关此的更多信息。 |
| 时区模块 | [可选]设置为1以使时区模块能够在API响应中包括时区数据。在时区模块部分阅读更多关于此的信息。 |
| bbox模块 | [可选]设置为1以使边界框模块能够在API响应中包括边界坐标。在边界框模块部分中了解更多信息。 |
| 限制 | [可选]指定1到80之间的限制，以限制每个地理编码查询返回的结果数。批处理请求可以包含多个地理编码查询。（默认值：10个结果） |
| 领域 | [可选]指定一个或多个响应字段以减小API响应大小。了解如何在指定响应字段部分中使用此选项。 |
| 输出 | [可选]指定首选的API输出格式。可用值：JSON（默认）、XML和GeoJSON。 |
| 回调 | [可选]使用此参数指定要将API响应包装在其中的JSONP回调函数名称。了解有关JSONP回调的更多信息。 |
响应对象
每个API响应由20个不同的响应对象组成：
| 响应对象 | 描述 |
| 数据 | 返回两个大的数据数组：请求和结果，下面将详细解释。 |
| 结果 | 返回此API请求的位置结果数组。子数组的数量直接取决于指定的限制值。下面列出了所有子阵列和子对象。 |
| 结果>纬度 | 返回与定位结果关联的纬度坐标。 |
| 结果>经度 | 返回与定位结果关联的经度坐标。 |
| 结果>标签 | 返回格式化的地名或地址。 |
| 结果>名称 | 返回定位结果的名称。这可能是一个地名、地址、邮政编码等等。 |
| 结果>类型 | 返回定位结果的类型。以下是所有可用的位置类型列表：地点，地址，街道，邻里，自治市，localadmin，地方，县，宏观国家，地区，宏观地区，国家，粗略，邮政编码。 |
| 结果>距离 | 返回定位结果与查询参数中指定的坐标之间的距离（以米为单位）。仅适用于反向地理编码。 |
| 结果>数量 | 返回与定位结果关联的街道或门牌号。 |
| 结果>街道 | 返回与定位结果关联的街道名称。 |
| 搜索结果>邮政编码 | 返回与位置结果关联的邮政编码或邮政编码。 |
| 结果>信心 | 返回与位置结果关联的介于0（0%置信度）和1（100%置信度）之间的置信度分数。 |
| 结果>区域 | 返回与定位结果关联的区域的名称。 |
| 结果>区域代码 | 返回与定位结果关联的区域代码。 |
| 结果>行政区域 | 返回与定位结果关联的行政区域的名称。 |
| 结果>邻域 | 返回与定位结果关联的邻域的名称。 |
| 结果>国家 | 返回与定位结果关联的国家/地区的通用名称。 |
| 结果>国家代码 | 返回与位置结果关联的国家/地区的ISO 3166 Alpha 2（两个字母）代码。 |
| 结果> map_url | 返回与定位结果关联的可嵌入映射。 |
如何使用 Node.js 执行正向地理编码？
positionstack API与所有主流编程语言兼容。
使用以下代码通过Node.js发出正向地理编码API请求：
const axios = require('axios');
const params = {
access_key: 'YOUR_ACCESS_KEY',
query: '1600 Pennsylvania Ave NW, Washington DC'
}
axios.get('http://api.positionstack.com/v1/forward', {params})
.then(response => {
console.log(response.data);
}).catch(error => {
console.log(error);
});以下是Node.js IDE内的API响应（在此示例中使用Atom）：
如何使用 Node.js 执行反向地理编码？
使用以下代码通过Node.js发出反向地理编码API请求，请记住，您需要输入纬度和经度来进行查询搜索：
const axios = require('axios');
const params = {
access_key: 'YOUR_ACCESS_KEY',
query: '38.897675, -77.036547'
}
axios.get('http://api.positionstack.com/v1/reverse', {params})
.then(response => {
console.log(response.data);
}).catch(error => {
console.log(error);
});以下是Node.js IDE内的API响应（在此，我在此示例中使用Atom）：
额外奖励：使用其他平台的 API 请求
如何使用 RAD Studio REST Debugger 发出 API 请求？
首先，下载 Delphi REST Debugger。
选择GET方法，并将请求发送到以下URL（反向地理编码的示例）：
http://api.positionstack.com/v1/reverse?access_key=YOUR_ACCESS_KEY&query=40.7638435,-73.9729691
在获得所需的API响应后，如果您想用Delphi来创建一个基于它的桌面应用程序，请参考本文：https://blogs.embarcadero.com/using-apilayer-rest-apis-from-delphi/
如何使用 Postman 发出 API 请求？
如果这是您第一次使用Postman，您可以在我们的博客文章中阅读有关安装指南：https://blog.apilayer.com/easily-spider-websites-using-node-js-and-powerful-rest-apis/
选择GET方法，并将请求发送到以下URL：
http://api.positionstack.com/v1/reverse?access_key=YOUR_ACCESS_KEY&query=40.7638435,-73.9729691
您准备好将强大的地理编码功能集成到您的应用程序中了吗？
如您所见，PositionStack REST API 提供了一系列精确的地理编码服务。无论是正向还是反向批量地理编码，都可以将这些API端点连接到您使用的任何平台和编程语言中。
在本文中，我们将向您展示如何使用 PositionStack REST API 进行基本的正向和反向地理编码操作。
利用 PositionStack 的免费层吧！如果您需要更强大的功能（例如 HTTPS 加密、扩展速率限制、JSON、XML、GeoJSON、嵌入式地图等），我们强烈建议您升级订阅计划。如果这还不够，请联系我们以获得定制解决方案。我们迫不及待地想看看您使用我们的REST API构建的内容！
常见问题
什么是地理编码？
地理编码是将地址转换为地图点。例如，它将“1600 Amphitheatre百老汇，山景，CA”更改为显示其在地图上位置的坐标（如纬度37.423021和经度-122.083739）。
地理编码的工作原理是什么？
地理编码是一种利用特殊服务（例如谷歌地图）在地图上精确定位一个地址的技术。它通过查询数据库、运用算法和分析地图数据来实现这一过程。
什么是反向地理编码？
反向地理编码则相反。它将坐标转换成人们可以理解的地址。例如，它会将纬度和经度更改为“1600 Amphitheatre百老汇，山景，CA”。
人们使用地理编码做什么？
地理编码有助于地图应用程序（如谷歌地图），查找附近的地方（如餐馆），以及使用地图分析和显示信息的系统。
地理编码有什么问题吗？
有时地理编码可能会出现错误，特别是在那些人口稀少的地区。此外，如果地址信息过时或者有误也可能会引发其它问题。由于地理编码常常需要共享位置数据，所以还涉及到隐私方面的考量。
如何找到更多同类API？
幂简集成是国内领先的API集成管理平台，专注于为开发者提供全面、高效、易用的API集成解决方案。幂简API平台可以通过以下两种方式找到所需API：通过关键词搜索API、或者从API Hub分类页进入寻找。
立即免费注册，开始将精确且丰富的正向和反向地理定位数据集成到您的应用程序中！
原文链接：https://blog.apilayer.com/how-to-get-started-with-powerful-a-geo-api-service-using-nodejs/
