Address service — search.vikvek.fi

search.vikvek.fi is the address lookup service our other systems run on. Type part of a street and you get streets; add a house number and you get buildings; ask for one of them and you get coordinates.

It is built on Finland's open building and address data (Ryhti / SYKE, CC BY 4.0) — roughly 3.9 million addresses. That data is national reference data: it is identical whichever application asks for it — which is exactly why it belongs in a service of its own rather than inside any single application.

What it is used for

• Address entry where a customer cannot type an address that does not exist
• Delivery fee and distance calculated from real coordinates
• Driver navigation to the right building
• One API for all our projects — address logic is not rewritten each time

How it works

The API has two endpoints: suggest (by search term, optionally biased toward the user's location) and retrieve (by the id a suggestion handed out, returning the full record and coordinates).

A street suggestion deliberately cannot be retrieved. A street's centroid can sit hundreds of metres from any actual building, and a delivery fee computed from it would quote somebody a price for somewhere they do not live. The application should ask for a house number, not guess one.

Every call is signed (HMAC-SHA256 within a timestamped window), and each client application has its own key and its own rate limit. Every authentication failure returns the same single answer: which half was wrong goes to the server log, not into a reply that helps someone keep guessing.

Technology

• PHP + MariaDB, a versioned REST API (/api/v1/)
• The open dataset imported into our own database, indexed for search
• HMAC signing, per-client rate limiting and full request logging
• Automated tests plus a separate smoke test against a real deployed host