Distance & map providers

For merchants

Instant Delivery is priced from the driving distance between your fulfilment location and the customer's delivery address. The plugin asks a map service two questions: where is this address? (geocoding) and how far is the drive? (routing). Everything else — rules, surcharges, the final price — is calculated inside the plugin.

External services

Geocoding and routing results come from Google or from the OpenStreetMap servers you configure. Which addresses they can find, how precise they are, quotas, prices and terms of use are set by those services and can't be verified without a live key or server. Test with real customer addresses from your area before going live.

Choose a provider

	OpenStreetMap (default)	Google Maps
Address lookup	Nominatim	Geocoding API
Driving distance	OSRM	Distance Matrix API (mode=driving)
Account	None for the public servers	Google Cloud project with billing
Setting	Map provider = OpenStreetMap (Nominatim + OSRM)	Map provider = Google Maps, plus Google Maps API key
Production	Public servers forbid heavy or commercial use (Nominatim: max. 1 request per second). Run your own Nominatim and OSRM and enter their URLs.	Billed per request by Google. Keep the distance cache at 30 days or less.

Both are set per sales channel in the configuration.

Google Maps

1. In the Google Cloud console, create or pick a project with billing enabled.
2. Enable the Geocoding API and the Distance Matrix API for the project.
3. Create an API key under APIs & Services → Credentials. If you restrict it, allow both APIs; the requests come from your shop server, not from the customer's browser.
4. Paste the key into Google Maps API key and choose Google Maps as map provider. Save.

Never share the key or paste it into a support ticket. If Google refuses the key — wrong restrictions, billing off, an API not enabled — the log shows REQUEST_DENIED, OVER_DAILY_LIMIT or INVALID_REQUEST at error level; see Troubleshooting.

OpenStreetMap

Nothing is required to try it: the defaults point to https://nominatim.openstreetmap.org and https://router.project-osrm.org. For production, host your own Nominatim and OSRM and enter their base URLs in Nominatim base URL and OSRM base URL. The plugin calls <nominatim>/search and <osrm>/route/v1/driving/…, and identifies itself to Nominatim with the user agent KmhLastMileDeliverySW/1.0 (Shopware plugin).

Set your fulfilment location

Fulfilment latitude and Fulfilment longitude are the starting point of every route. Each storefront can have its own location (sales channel selector); one storefront can have only one.

Which addresses are priced

The plugin builds the address from the shipping address in checkout: street, postcode city, country. Street and city must be filled, otherwise checkout shows Please enter a complete delivery address….

The address must be found at street level:

• Google results that are only an approximate area (location_type APPROXIMATE — a postcode, city, region or country centre) count as not found.
• Nominatim results ranked below street level (place_rank under 26) count as not found.

Otherwise a mistyped address would be priced from the middle of a city or country. An address that isn't found shows We could not determine the delivery distance… in checkout.

Google can match a real street even when the city or postcode is wrong (a partial street-level match); that address is then priced from the matched street.

Time-outs

Each map request gives up after 3 seconds without a response or 5 seconds in total, so a slow map service can't hold checkout up for long. The customer then sees We could not determine the delivery distance… and can try again or choose another shipping method.

Caching

To save requests (and money with Google), each measured distance is cached:

• Per map provider, fulfilment location and address. Changing the provider or the coordinates starts fresh lookups.
• Address normalised for the cache: the same address typed with different upper/lower case, extra spaces or spacing around commas reuses the entry.
• For the Distance cache TTL — 30 days by default.
• Addresses that can't be found are remembered as not found for 1 hour, so repeated cart updates don't call the map service again. Errors from the map service (time-outs, refused key) are not cached.
• The cache lives in Shopware's application cache: bin/console cache:clear (or Settings → System → Caches & indexes → Clear cache) empties it.

Privacy

The customer's delivery address is sent to the map service you choose. With Enable debug logging on, map requests and responses — including the address — are written to the plugin log at info level; the Google API key is masked as ***. Mention the map service in your privacy policy.