mapricot 0.1.0__py3-none-any.whl

mapricot/__init__.py

@@ -0,0 +1,252 @@
+"""Official client for the Mapricot API: geocoding, places, routing, and IP geolocation."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Literal, NotRequired, Sequence, TypedDict
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Account",
+    "Address",
+    "Attribution",
+    "IpLocation",
+    "Leg",
+    "Mapricot",
+    "MapricotError",
+    "Place",
+    "PlaceResult",
+    "Places",
+    "Point",
+    "Route",
+    "Routes",
+]
+
+
+class Point(TypedDict):
+    lat: float
+    lon: float
+
+
+class Attribution(TypedDict):
+    source: str
+    text: str
+    url: str
+
+
+class Address(TypedDict, total=False):
+    houseNumber: str
+    street: str
+    postalCode: str
+    locality: str
+    region: str
+    regionCode: str
+    country: str
+    countryCode: str
+
+
+class Place(TypedDict):
+    id: str
+    type: str
+    name: str
+    label: str
+    lat: float
+    lon: float
+    address: NotRequired[Address]
+    categories: NotRequired[list[str]]
+    distanceMeters: NotRequired[int]
+    source: str
+
+
+class Places(TypedDict):
+    results: list[Place]
+    attribution: list[Attribution]
+
+
+class PlaceResult(TypedDict):
+    result: Place
+    attribution: list[Attribution]
+
+
+class Leg(TypedDict):
+    distanceMeters: int
+    durationSeconds: int
+
+
+class Route(TypedDict):
+    distanceMeters: int
+    durationSeconds: int
+    polyline: str
+    """Encoded polyline with six decimal places of precision."""
+    legs: list[Leg]
+
+
+class Routes(TypedDict):
+    routes: list[Route]
+    attribution: NotRequired[list[Attribution]]
+
+
+class IpLocation(TypedDict):
+    ip: str
+    found: bool
+    continentCode: NotRequired[str]
+    countryCode: NotRequired[str]
+    countryName: NotRequired[str]
+    regionCode: NotRequired[str]
+    regionName: NotRequired[str]
+    city: NotRequired[str]
+    location: NotRequired[Point]
+    source: str
+    attributionUrl: str
+    licenseUrl: str
+    datasetRelease: str
+
+
+class Account(TypedDict):
+    id: str
+    name: str
+    status: str
+    created_at: str
+
+
+class MapricotError(Exception):
+    """An error response from the API, with its HTTP status, error code, and request ID."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: str | None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+
+
+class Mapricot:
+    """A client for https://api.mapricot.com. The key defaults to the MAPRICOT_KEY environment variable."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = "https://api.mapricot.com",
+        timeout: float = 30,
+        max_retries: int = 2,
+    ):
+        api_key = api_key or os.environ.get("MAPRICOT_KEY")
+        if not api_key:
+            raise ValueError("Pass api_key or set MAPRICOT_KEY.")
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    def search(
+        self,
+        q: str,
+        *,
+        focus: Point | None = None,
+        country: str | Sequence[str] | None = None,
+        limit: int | None = None,
+        lang: str | None = None,
+    ) -> Places:
+        """Find addresses and places matching free text."""
+        return self._request("GET", "/v1/search", q=q, focus=focus, country=country, limit=limit, lang=lang)
+
+    def autocomplete(
+        self,
+        q: str,
+        *,
+        focus: Point | None = None,
+        country: str | Sequence[str] | None = None,
+        limit: int | None = None,
+        lang: str | None = None,
+    ) -> Places:
+        """Suggest addresses and places as someone types."""
+        return self._request("GET", "/v1/autocomplete", q=q, focus=focus, country=country, limit=limit, lang=lang)
+
+    def reverse(self, lat: float, lon: float, *, limit: int | None = None, lang: str | None = None) -> Places:
+        """Find the address nearest a coordinate, or the area around it."""
+        return self._request("GET", "/v1/reverse", lat=lat, lon=lon, limit=limit, lang=lang)
+
+    def nearby(
+        self,
+        lat: float,
+        lon: float,
+        *,
+        category: str | Sequence[str] | None = None,
+        radius: int | None = None,
+        limit: int | None = None,
+        lang: str | None = None,
+    ) -> Places:
+        """List places around a coordinate, optionally by category."""
+        return self._request(
+            "GET", "/v1/nearby", lat=lat, lon=lon, category=category, radius=radius, limit=limit, lang=lang
+        )
+
+    def place(self, id: str, *, lang: str | None = None) -> PlaceResult:
+        """Look up one place by its Mapricot ID."""
+        return self._request("GET", f"/v1/places/{urllib.parse.quote(id, safe='')}", lang=lang)
+
+    def route(self, waypoints: Sequence[Point], *, mode: Literal["drive", "walk", "bicycle"] | None = None) -> Routes:
+        """Find a route through 2 to 20 waypoints."""
+        body: dict[str, Any] = {"waypoints": list(waypoints)}
+        if mode:
+            body["mode"] = mode
+        return self._request("POST", "/v1/route", body=body)
+
+    def ip(self, address: str) -> IpLocation:
+        """Approximate location of a public IP address."""
+        return self._request("GET", f"/v1/ip/{urllib.parse.quote(address, safe='')}")
+
+    def account(self) -> Account:
+        """The key's account. Not billed, so it checks a key for free."""
+        return self._request("GET", "/v1/account")
+
+    def _request(self, method: str, path: str, body: dict[str, Any] | None = None, **params: Any) -> Any:
+        query = urllib.parse.urlencode({name: _format(value) for name, value in params.items() if value is not None})
+        url = self._base_url + path + (f"?{query}" if query else "")
+        headers = {"Authorization": f"Bearer {self._api_key}", "User-Agent": f"mapricot-python/{__version__}"}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                    return json.load(response)
+            except urllib.error.HTTPError as response:
+                with response:
+                    error = _error_from(response)
+            if attempt >= self._max_retries or not _retryable(error):
+                raise error
+            time.sleep(0.5 * 2**attempt)
+            attempt += 1
+
+
+def _format(value: Any) -> str:
+    if isinstance(value, dict):
+        return f"{value['lat']},{value['lon']}"
+    if isinstance(value, (list, tuple)):
+        return ",".join(value)
+    return str(value)
+
+
+def _error_from(response: urllib.error.HTTPError) -> MapricotError:
+    request_id = response.headers.get("X-Request-Id")
+    try:
+        error = json.load(response)["error"]
+        return MapricotError(response.code, error["code"], error["message"], request_id)
+    except (ValueError, KeyError, TypeError):
+        return MapricotError(response.code, "unknown", f"HTTP {response.code}", request_id)
+
+
+def _retryable(error: MapricotError) -> bool:
+    return error.status == 503 or error.code == "concurrency_exceeded"

mapricot-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: mapricot
+Version: 0.1.0
+Summary: Official client for the Mapricot API: geocoding, places, routing, and IP geolocation.
+Project-URL: Homepage, https://mapricot.com/
+Project-URL: Documentation, https://mapricot.com/docs/python/
+Project-URL: Source, https://github.com/mapricothq/mapricot/tree/main/sdks/python
+Project-URL: Issues, https://github.com/mapricothq/mapricot/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: geocoding,ip-geolocation,maps,places,routing
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Mapricot for Python
+
+The official Python client for the [Mapricot API](https://mapricot.com/): address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every month.
+
+```sh
+pip install mapricot
+```
+
+It needs Python 3.11 or later and has no dependencies.
+
+## Quick start
+
+Create a server key in the [dashboard](https://app.mapricot.com/) and set it as `MAPRICOT_KEY`:
+
+```sh
+export MAPRICOT_KEY="mapricot_sk_…"
+```
+
+```python
+from mapricot import Mapricot
+
+client = Mapricot()
+
+data = client.search("128 SW 3rd Ave, Portland", limit=1)
+place = data["results"][0]
+print(place["label"], place["lat"], place["lon"])
+```
+
+Pass the key yourself with `Mapricot("mapricot_sk_…")`.
+
+## Methods
+
+Each method returns the API's JSON as a typed dict, with the same field names as the [API reference](https://mapricot.com/api-reference/).
+
+| Method | Endpoint |
+| --- | --- |
+| `client.search(q, focus=, country=, limit=, lang=)` | [`GET /v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `client.autocomplete(q, focus=, country=, limit=, lang=)` | [`GET /v1/autocomplete`](https://mapricot.com/docs/places/#suggest-as-people-type) |
+| `client.reverse(lat, lon, limit=, lang=)` | [`GET /v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
+| `client.nearby(lat, lon, category=, radius=, limit=, lang=)` | [`GET /v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
+| `client.place(id, lang=)` | [`GET /v1/places/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
+| `client.route(waypoints, mode=)` | [`POST /v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
+| `client.ip(address)` | [`GET /v1/ip/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
+| `client.account()` | `GET /v1/account`, which checks a key and is never billed |
+
+`focus` and each waypoint are `{"lat": …, "lon": …}`. `country` and `category` take a list or a comma-separated string.
+
+```python
+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 `polyline` is encoded with six decimal places. Decode it with precision 6, as [decoding a route polyline](https://mapricot.com/docs/polyline/) shows.
+
+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`:
+
+```python
+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](https://mapricot.com/api-reference/#errors) lists every status.
+
+## Links
+
+- [Mapricot](https://mapricot.com/)
+- [Python docs](https://mapricot.com/docs/python/)
+- [API reference](https://mapricot.com/api-reference/)
+- [Pricing](https://mapricot.com/pricing/)

mapricot-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+mapricot/__init__.py,sha256=eodNIKM-Nr8UEncDvSuPBQUfe-QPU9YSDBpcZ8dnBPo,7414
+mapricot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapricot-0.1.0.dist-info/METADATA,sha256=5PiBMtkEQhuD_H-H2FtWzukPNOytxbw4_pwlJEs-u2k,4012
+mapricot-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mapricot-0.1.0.dist-info/licenses/LICENSE,sha256=XUUyLYEmz15umsXVNEkVcw3d91W2_Rku0WVCnv80YFQ,1065
+mapricot-0.1.0.dist-info/RECORD,,

mapricot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mapricot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mapricot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.