Mapricot for Python

The official Python client for the Mapricot API: address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every month.

pip install mapricot

It needs Python 3.11 or later and has no dependencies.

Quick start

Create a server key in the dashboard and pass it to the client. Keep it out of your source code, for example by reading it from an environment variable as here.

import os

from mapricot import Mapricot

client = Mapricot(os.environ["MAPRICOT_KEY"])

data = client.search("128 SW 3rd Ave, Portland", limit=1)
place = data["results"][0]
print(place["label"], place["lat"], place["lon"])

Methods

Each method returns the API's JSON as a typed dict, with the same field names as the API reference.

focus and each waypoint are {"lat": …, "lon": …}. country and category take a list or a comma-separated string.

nearby = client.nearby(45.52, -122.68, category=["food:coffee_shop"], radius=1000)
route = client.route([{"lat": 45.5189, "lon": -122.6793}, {"lat": 45.5214, "lon": -122.6828}], mode="walk")
print(route["routes"][0]["durationSeconds"])

A route's path comes as an encoded polyline with five decimal places, which polyline decoders assume. Pass geometries="geojson" to get it as a GeoJSON LineString in geometry instead, which maps draw without decoding, or geometries="polyline6" for six decimal places.

If your app shows results, show the credits in each response's attribution.

Errors and retries

An error response raises MapricotError, with the HTTP status, the API's error code, a message, and the request_id:

from mapricot import MapricotError

try:
    client.search("")
except MapricotError as error:
    print(error.status, error.code, error.message)  # 400 invalid_request The service rejected the request.

The client retries 503 responses and 429 concurrency_exceeded, up to twice, waiting longer each time. Errors aren't billed. Set max_retries= and timeout= (seconds) on Mapricot(...) to change this. The API reference lists every status.

Links

• Mapricot
• Python docs
• API reference
• Pricing