amap-collector 0.3.1

A scraper of the french AMAP network returning structured information.

AMAP collector

This scraper collects the fragmented information of the french AMAP network from several web sources:

• AMAP Île-de-France;
• AMAP Haute-Normandie;
• Inter AMAP 44 (Nantes et Loire-Atlantique);
• AMAP for the rest of France;

It returns the targeted information in JSON or CSV formats.

Usage

The client can be imported as a package or launched in the command line via the cli. See the embedded docstrings for full documentation on parameters or read this README further.

Package usage

The typical use case is importing a specific AMAP client (e.g. IdfAmapClient, HnAmapClient, etc) in your code, and its error class eventually.

The AMAP client object exposes a fluent interface to easily set the target parameters. Here below an example of integration to fetch results around the 75th department (Paris area) over 10 km radius:

from amap_collector.core.idf import IdfAmapClient

c = IdfAmapClient().with_department(75).with_km_radius(10)
results = c.get_amap_list()

where results is a list of dicts like:

{
  "name": "AMAP Coquéron",
  "status": "available_places",
  "website": "",
  "contact": {
  "name": "Agnès",
  "emails": [
      "[e-mail]",
      "[e-mail]"
  ],
  "phones": [
      "01 XX XX XX XX",
      "07 XX XX XX XX"
  ]
  },
      "place": {
      "name": "Sauvegarde Paris",
      "address": "3 rue Coq Héron, 75001 PARIS",
      "delivery_time": "Mardi 17H-19H"
  },
  "comment": "Venez nombreux"
}

Concurrent scraping

You can also run the scraper concurrently, on multiple area codes:

import asyncio
from amap_collector.core.collector import collect

results = asyncio.run(collect(["75", "19", "80"], max_concurrent=4))

Or inside an async function:

from amap_collector.core.collector import collect

async def main():
    results = await collect(["75", "19", "80"], max_concurrent=4)

Note: max_concurrent has a default equal to 8.

Cli usage

The cli is built with Typer, you can explore command parameters and options via the --help modifier:

area_code A valid french department code or zip code; the latter (zip code) is applicable to the IDF scraper only

--farms-only Collect only farm information (applicable to HN and IA44 scrapers only)

--km-radius The Search radius in km (available options: 2, 5, 10, 15, 20) [default: 2]; this options is only valid for Île-de-France

--output-file The otput file path (.json or .csv)

--help It summarizes all these parameters and exit

Note 1: Results are shown by default in the standard output, unless a file path is specified via the --output-file modifier (JSON and CSV formats are only supported).

Note 2: The executable command name exposed after package installation is amap_collector.

Docker containerization

Build image

docker build -t amap-collector .

Run the command

Pass any amap_collector option directly after the image name:

# stdout — all AMAPs in dept 93 within 5 km
docker run --rm amap-collector 93 --km-radius 5

# save to a JSON file on the host
docker run --rm -v /tmp:/out amap-collector 75 --output-file /out/amaps.json

# narrow collection by zip code
docker run --rm amap-collector 75012

# collection of farms only, without their AMAPS
docker run --rm amap-collector 76 --farms-only

# concurrent collection with multiple departments
docker run --rm amap-collector 75,18,27

Run tests

Tests require the dev dependencies. Run them with:

uv run pytest

To run a specific test file:

uv run pytest tests/core/test_parser.py -v

Run the linter

Using ruff for linting:

docker run --rm amap-collector uv run --with ruff ruff check .

Run the type checker

Using ty:

uv run ty check .

Contributing

Contributions are welcome — feel free to open issues and pull requests for bug fixes and feature requests.

After cloning the repo, activate the git hooks to run type checks locally before each commit:

git config core.hooksPath .githooks