picarta 1.2.1

A package to geolocate images from URL or local files using Picarta AI

Picarta

A Python package to geolocate images from URL or local files using Picarta.ai API 🌍🔍.

Overview

The Picarta Image Geolocalization API allows users to localize images and obtain predictions about their geographic location based on their content and/or embedded metadata. Users can provide an image either from a local file or via a URL and receive predictions about the location depicted in the image. The API returns information such as city, province, country, GPS coordinates, and confidence scores for each prediction.

Authentication

To access the API, users need to provide an API token in the request headers. Users can obtain an API token by registering on the Picarta website.

Installation

To install the picarta package, use pip:

pip install picarta

Usage

Request Format

The API accepts HTTP POST requests with a JSON payload containing the following parameters:

• TOKEN: User's API token.
• IMAGE: image path or URL of the image to localize.
• TOP_K (Optional): Number of top predictions to return (default is 3, maximum is 10).
• COUNTRY_CODE (Optional): 2-letter country code to limit search to a specific country (e.g., "US", "FR", "DE").
• ADMIN1 (Optional): Admin1 region name (e.g., "California", "Niedersachsen", "Toscana"). Must be used with COUNTRY_CODE.
• Center_LATITUDE (Optional): Latitude of the center of the search area.
• Center_LONGITUDE (Optional): Longitude of the center of the search area.
• RADIUS (Optional): Radius of the search area around the center point in kilometers (maximum 25km).

Search Priority

When using location filters, the API searches in the following priority order:

1. Admin1 + Country (if both provided and admin1 is supported)
2. Country (if only country provided, or admin1 not supported)
3. Worldwide (if no location filters provided)

Get Supported Admin1 Regions

To get the list of supported admin1 regions for a country:

from picarta import Picarta

localizer = Picarta("YOUR_API_TOKEN")
result = localizer.get_admin1_regions("IT")
print(result)

Example response:

{
  "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"
}

Example Request using the picarta Package

from picarta import Picarta

api_token = "YOUR_API_TOKEN"
localizer = Picarta(api_token)

# Geolocate a local image worldwide
result = localizer.localize(img_path="/path/to/local/image.jpg")

print(result)

# Geolocate an image within a specific admin1 region
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)

# Geolocate with zone search (center point + radius)
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)

Response Format

The API returns a JSON object containing geographic location results, including metadata about the image and a dictionary of topk predictions.

Example API Response

{
  "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"
}

No Match Found Response

When using location filters (COUNTRY_CODE, ADMIN1, Center_LATITUDE/Center_LONGITUDE/RADIUS), the API may not find a matching location within the specified search area. In this case, the response will include a message field and an empty topk_predictions_dict. No credits are deducted from your account for this search.

{
  "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."
}

To handle this in your code, check for the message field or an empty 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"])

Tips: If you receive this response, try enlarging the search radius or searching in a different region.

Additional Notes

• topk_predictions_dict is presented in the second version of the API.
• topk_predictions_dict[1] is equal to province, ai_country, city, ai_lat, ai_lon, and ai_confidence. (It shows the top 1 result, which was in the first version of the API).
• The API could also return the following values if the EXIF data exists in the images:
  • exif_lat: Latitude from EXIF metadata.
  • exif_lon: Longitude from EXIF metadata.
  • exif_country: Country name from EXIF metadata.
• For aerial and satellite images, please refer to this repository: Aerial-Imagery.

Contact Information

For any inquiries or assistance, feel free to contact us via:

• Email: [e-mail]
• Discord: Join our Discord channel
• Share your feedback: API Feedback Survey