Metadata-Version: 2.5
Name: alpin-api
Version: 0.3.0
Summary: Deterministic forum scraping for Alpine ski-resort updates
Author: Michael Medek
License: MIT License
        
        Copyright (c) 2026 Michael Medek
        
        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.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: curl-cffi>=0.13
Requires-Dist: requests>=2.32
Requires-Dist: tqdm>=4.67
Provides-Extra: tracker
Requires-Dist: groq>=0.31; extra == 'tracker'
Description-Content-Type: text/markdown

# alpin-api

Every night, this project turns posts from dedicated Alpine ski-resort forum topics into a public GeoJSON map of the latest construction and infrastructure progress.

[View the live interactive map](https://michaelmedek.github.io/alpin-api/)

## For developers

You can install the `alpin_api` Python package from PyPI: its forum scrapers, `AlpinAPI`, data types, and deterministic resort/topic constants. The installed package reads live forum pages. The repository's Groq analysis, map generation, nightly automation, and file-writing application are not included in the published package.

```shell
pip install alpin-api
```

Or add it to a uv project:

```shell
uv add alpin-api
```

## Forum access requirements

Some forums require FlareSolverr listening on `localhost:8191`; the package connects to that service.
Start FlareSolverr before using:

```shell
docker run --rm --detach --name flaresolverr --publish 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest
```

## Examples

Choose the path that matches what you already know.

If you want updates for one registered resort, fetch recent posts from all assigned topics or restrict the request to one forum:

```python
from alpin_api import AlpinAPI, Forum, SKI_RESORTS

# List all registered resorts and their names
print("\n".join(f"{resort_id}: {resort.name}" for resort_id, resort in SKI_RESORTS.items()))

posts_by_resort = AlpinAPI().fetch_posts(
    resort_ids=["hintertuxer_gletscher"],  # None fetches all registered resorts
    days_old_max=14,
    forum=Forum.ALPINFANS,  # None fetches every forum assigned to the resort
)
hintertux_posts = posts_by_resort["hintertuxer_gletscher"]
```

If you first want to see what people are discussing on a forum, discover its latest topics:

```python
from alpin_api import AlpinAPI, Forum

api = AlpinAPI()
latest_topics = api.fetch_latest_topics(
    forum=Forum.ALPINFANS,
    topic_limit=20,
)
for topic in latest_topics:
    print(topic.topic_id, topic.title)
```

Then select an interesting result and fetch its recent posts:

```python
selected_topic = latest_topics[0]
topic_posts = api.fetch_topic_posts(
    forum=selected_topic.forum,
    topic_identifier=selected_topic.canonical_url,
    days_old_max=5,
)
```

## Retrieval boundaries

- `days_old_max` is a rolling clock window, so `1` means exactly 24 hours backward. It intentionally reads the newest page and at most the immediately preceding page.
- `forum` filters topics to the selected forum before any request and requires every selected resort to have a registered topic there. `None` reads every assigned forum.
- `topic_limit` applies separately to every discovery listing configured for a forum news and construction topics.

## Development

Install the locked development environment and the repository's Git hooks:

```shell
uv sync --extra tracker
uv run pre-commit install
```

Run every configured hook with `uv run pre-commit run --all-files`.
