PPMatcher — run it

PPMatcher finds the nearest pickup / drop-off points for a customer's address (CZ + PL: DPD, GLS, InPost) and re-ranks them by real road distance. It is a small backend service plus an embeddable checkout widget.

This repository contains everything you need to run it. No source code, no build step — you pull a prebuilt image and start it.

Requirements

• Docker + Docker Compose (Docker Desktop on Windows/Mac).

Run it

docker compose up

That pulls the prebuilt image and starts the service. Then open:

URL	What
http://localhost:8000/	Live demo (search box + map)
http://localhost:8000/docs	API documentation
http://localhost:8000/health	Health check

Try Václavské náměstí 1, Praha (country CZ) or Marszałkowska 1, Warszawa (country PL). Stop it with Ctrl+C, or docker compose down.

Add it to your checkout

The finder is an embeddable widget. Put this where the pickup-point selector should appear in your checkout page:

<div id="ppmatcher"></div>

<script>
  window.PPMATCHER_CONFIG = {
    apiUrl: 'http://localhost:8000',   // the running backend (your hosted URL in production)
    mount:  '#ppmatcher',
    country: 'CZ',
    carriers: ['DPD', 'GLS', 'INPST'],
    onSelect: function (point) {
      // Called when the customer picks a point. Store it on the order, e.g.
      // point.service_point_id and point.carrier_code.
      console.log('selected pickup point', point);
    }
  };
</script>
<script src="http://localhost:8000/widget.js"></script>

It loads its map library automatically and needs no build step. The widget is plain JavaScript, so it works on any checkout (Magento, custom, etc.) — there is no framework or platform version requirement.

The API

POST /pickup-points/search

// request
{ "address": "Václavské náměstí 1, Praha", "country_code": "CZ", "limit": 5, "carrier_code": "DPD" }

carrier_code is optional. The response returns the nearest points with both straight-line (distance_km) and real road distance (road_distance_km), plus a ranking field. Full schema at /docs.

Configuration

Variable	Default	Purpose
ENABLE_ROUTING	1	0 disables road re-ranking (straight-line only).
OSRM_BASE_URL	public OSRM demo	Routing endpoint. Use your own OSRM for production.
ROUTE_PREFILTER	25	How many nearest candidates get road-distance scoring.

Set these under environment: in docker-compose.yml.