Metadata-Version: 2.4
Name: mapfy
Version: 0.1.1
Summary: Search Google Maps places and return normalized data with image URLs
Keywords: google-maps,street-view,places,maps,scraper
Author: Henrique Moreira
Author-email: Henrique Moreira <78804989+henrique-coder@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: curl-cffi>=0.16.0
Requires-Dist: pydantic>=2.10.0,<3.0.0
Requires-Dist: orjson>=3.0.0
Requires-Python: >=3.11, <3.16
Project-URL: Homepage, https://github.com/henrique-coder/mapfy
Project-URL: Repository, https://github.com/henrique-coder/mapfy.git
Project-URL: Issues, https://github.com/henrique-coder/mapfy/issues
Description-Content-Type: text/markdown

# Mapfy

Mapfy queries public Google Maps results, normalizes each candidate as a
`PlaceResult`, builds a direct Google Maps link, and returns a single Street View
image URL when one is available.

## What it returns

Each result can include `place_id`, `name`, `category`, `address`, `website`,
`rating`, `reviews_count`, `latitude`, `longitude`, `maps_url`, and `image_url`.
`maps_url` opens the location in Google Maps; `image_url` points to its Street
View image and does not expose the panorama ID separately.

Mapfy uses an internal Maps endpoint that Google does not document. Changes to
the response format may require a parser update.

## Public API

The client exposes two searches:

- `search()`: resolves an address, coordinates, or free-text location query.
- `search_places()`: finds establishments by name, category, or type.

## Installation

```bash
uv add mapfy
```

## Usage

```python
from mapfy import Mapfy

with Mapfy() as client:
    places = client.search_places(
        query="coffee shop",
        near="Seattle, WA",
        limit=10,
    )

for place in places:
    print(place.name, place.maps_url, place.image_url)
```

`near` is optional and accepts an address, a coordinate string (`"47.61,-122.33"`),
or a coordinate tuple (`(47.61, -122.33)`). `language` and `country` are optional;
when omitted, Google determines the request context.

`limit=None` returns every result received. A positive integer returns up to that
many results while preserving the order returned by Maps.

`search()` preserves every candidate returned by Maps, so ambiguous addresses do
not get reduced to an arbitrary first result.

```python
addresses = client.search("47.61, -122.33")
```

## Structure

```text
src/mapfy/
├── client.py
├── models.py
├── parser.py
├── common.py
└── __init__.py
```

## Development

```bash
uv sync --no-dev --group lint --group test
uv run ruff format
uv run ruff check
uv run ty check
```
