PicartaAI/Picarta-API

# Picarta-API [Picarta.ai](https://picarta.ai) 图像地理定位 API 🌍🔍 ### 概述 Picarta 图像地理定位 [API](https://picarta.ai/api) 允许用户根据图像内容及/或嵌入的元数据来定位图像并获取其地理位置预测。用户可以通过本地文件或 URL 提供图像，并接收关于图像所展示位置的预测信息。API 会返回城市、省份、国家、GPS 坐标以及每个预测的置信度分数。 ### 认证 要访问 [API](https://picarta.ai/api)，用户需要在请求头中提供 API 令牌。用户可以在 [Picarta](https://picarta.ai) 网站上注册以获取 API 令牌。**新账户可获得 10 次免费 API 积分用于测试服务**，只需从账户页面生成令牌即可开始使用。 ### 安装 要安装 `picarta` 包，请使用 pip： ``` pip install picarta ``` ### 用法 #### 请求格式 API 接受包含以下参数的 JSON 格式的 HTTP POST 请求： - `TOKEN`：用户的 API 令牌。 - `IMAGE`：要定位的图像路径或 URL。 - `TOP_K`（可选）：返回的预测数量（默认为 3，最大为 10）。 - `COUNTRY_CODE`（可选）：用于限制搜索范围的 2 位国家代码（例如 "US"、"FR"、"DE"）。 - `ADMIN1`（可选）：Admin1 区域名称（例如 "California"、"Niedersachsen"、"Toscana"）。必须与 `COUNTRY_CODE` 一起使用。 - `Center_LATITUDE`（可选）：搜索区域中心的纬度。 - `Center_LONGITUDE`（可选）：搜索区域中心的经度。 - `RADIUS`（可选）：以中心点为圆心的搜索区域半径（最大 25 公里）。 #### 搜索优先级 在使用位置过滤器时，API 按照以下优先级顺序进行搜索： 1. **Admin1 + 国家**（如果同时提供且该国家支持 admin1） 2. **国家**（如果仅提供国家，或不支持 admin1） 3. **全球范围**（如果未提供任何位置过滤器） #### 使用 `picarta` 包的示例请求 ``` from picarta import Picarta api_token = "YOUR_API_TOKEN" localizer = Picarta(api_token) # 在全球范围内定位本地图像 result = localizer.localize(img_path="/path/to/local/image.jpg") print(result) # 在特定 admin1 区域内定位图像 result = localizer.localize( img_path="https://upload.wikimedia.org/wikipedia/commons/8/83/San_Gimignano_03.jpg", top_k=3, country_code="IT", admin1="Toscana" ) print(result) # 使用区域搜索（中心点 + 半径）进行定位 result = localizer.localize( img_path="https://upload.wikimedia.org/wikipedia/commons/8/83/San_Gimignano_03.jpg", top_k=3, country_code="IT", admin1="Toscana", center_latitude=43.464, center_longitude=11.038, radius=25 ) print(result) ``` #### 获取支持的 Admin1 区域 使用 `picarta` 包： ``` from picarta import Picarta localizer = Picarta("YOUR_API_TOKEN") result = localizer.get_admin1_regions("IT") print(result) ``` 或通过 GET 请求： ``` GET https://picarta.ai/admin1/{country_code} ``` 对 `GET /admin1/IT` 的示例响应： ``` { "admin1_regions": ["Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige", "Umbria", "Valle d'Aosta", "Veneto"], "country_code": "IT" } ``` 如果某个国家不支持 admin1： ``` { "admin1_regions": [], "country_code": "AD", "message": "Admin1 search not supported for this country. Use country-level search." } ``` #### 不使用 `picarta` 包的示例请求 ``` import requests import json import base64 url = "https://picarta.ai/classify" api_token = "API_TOKEN" top_k = 3 headers = {"Content-Type": "application/json"} # 从本地文件或 URL 读取图像 with open("path/to/local/image.jpg", "rb") as image_file: img_path = base64.b64encode(image_file.read()).decode('utf-8') # 或 # img_path = "https://upload.wikimedia.org/wikipedia/commons/8/83/San_Gimignano_03.jpg" # 用于特定位置搜索的可选参数 country_code = "IT" admin1 = "Toscana" center_latitude, center_longitude, radius = None, None, None payload = {"TOKEN": api_token, "IMAGE": img_path, "TOP_K": top_k, "COUNTRY_CODE": country_code, "ADMIN1": admin1, "Center_LATITUDE": center_latitude, "Center_LONGITUDE": center_longitude, "RADIUS": radius} response = requests.post(url, headers=headers, json=payload) if response.status_code == 200: result = response.json() print(result) else: print("Request failed with status code:", response.status_code) print(response.text) ``` #### 响应格式 API 返回一个包含地理定位结果的 JSON 对象，其中包括图像元数据和 topk 预测字典。 #### 示例 API 响应 ``` { "topk_predictions_dict": { "1": { "address": {"city": "San Gimignano", "country": "Italy", "province": "Tuscany"}, "confidence": 0.9429214000701904, "gps": [43.46722412109375, 11.04349136352539] }, "2": { "address": {"city": "San Gimignano", "country": "Italy", "province": "Tuscany"}, "confidence": 0.8665691614151001, "gps": [43.4670295715332, 11.040340423583984] }, "3": { "address": {"city": "San Gimignano", "country": "Italy", "province": "Tuscany"}, "confidence": 0.8580218553543091, "gps": [43.4670295715332, 11.040340423583984] } }, "ai_confidence": 0.9429214000701904, "ai_country": "Italy", "ai_lat": 43.46722412109375, "ai_lon": 11.04349136352539, "camera_maker": "NIKON CORPORATION", "camera_model": "NIKON D200", "city": "San Gimignano", "province": "Tuscany", "timestamp": "2010:09:21 12:04:46" } ``` #### 未找到匹配的响应 当使用位置过滤器（`COUNTRY_CODE`、`ADMIN1`、`Center_LATITUDE`/`Center_LONGITUDE`/`RADIUS`）时，API 可能无法在指定的搜索区域内找到匹配位置。在这种情况下，响应将包含 `message` 字段和一个空的 `topk_predictions_dict`。**此次搜索不会从账户中扣除任何积分。** ``` { "camera_maker": "NIKON CORPORATION", "camera_model": "NIKON D200", "timestamp": "2010:09:21 12:04:46", "topk_predictions_dict": {}, "message": "No matching location was found within the specified search area. No credits were deducted from your account." } ``` 要在代码中处理这种情况，请检查 `message` 字段或空的 `topk_predictions_dict`： ``` result = localizer.localize(img_path="image.jpg", country_code="US", admin1="California") if "message" in result: print(result["message"]) # Try enlarging the search radius or searching in a different area else: print(result["topk_predictions_dict"]) ``` **提示：** 如果收到此响应，请尝试增大搜索半径或在不同区域进行搜索。 #### 附加说明 - `topk_predictions_dict` 在 API 第二版中提供。 - `topk_predictions_dict[1]` 等同于 province、ai_country、city、ai_lat、ai_lon 和 ai_confidence。（它显示第一个结果，对应 API 第一版本）。 - 如果图像中存在 EXIF 数据，API 还可能返回以下值： - `exif_lat`：来自 EXIF 元数据的纬度。 - `exif_lon`：来自 EXIF 元数据的经度。 - `exif_country`：来自 EXIF 元数据的国家名称。 - 关于航空和卫星图像，请参考该仓库：[Aerial-Imagery](https://github.com/PicartaAI/Picarta-Aerial-Imagery.git)。 ### 联系方式 如有任何咨询或帮助，请通过以下方式联系我们： - 电子邮件：[info@picarta.ai](mailto:info@picarta.ai) - Discord：[加入我们的 Discord 频道](https://discord.gg/g5BAd2UFbs) - 反馈建议：[API 反馈调查](https://forms.gle/JokVe1ZRKP1hjsA49)

标签：AI 图像分析, AI 地理识别, API, API 令牌, GPS, Homebrew安装, HTTP POST, JSON, pip install, Python 包, Python脚本, REST API, Top K 预测, URL, 中心点坐标, 位置服务, 位置预测, 元数据, 免费额度, 国家代码过滤, 国家识别, 图像地理定位, 图像识别, 图片位置识别, 地理坐标, 地理定位, 城市识别, 搜索半径, 搜索引擎优化, 本地文件, 省份识别, 置信度, 行政区域过滤, 认证, 逆向工具, 遥感