[Free Extension] Photon Address Autocomplete – OpenStreetMap-based address autofill

[gim]

Hi all,

I'd like to share a free, open-source extension that adds address autocomplete to EspoCRM address fields, powered by the Photon geocoder (OpenStreetMap data).

Type in the street field, pick a suggestion – street, postal code, city, state and country are filled in together.

**Features**

- Server-side proxy route (no CORS, authenticated via the regular Espo session, cached)
- Country selection via the standard Address Countries admin list ("Is Preferred" flag), with an optional override on the extension's settings page
- Already filled city/postal code/country guide the search via Photon's location bias – nearby matches rank first, everything else stays findable (zoom and weight configurable)
- Works on Account, Contact, Lead and RealEstateProperty; any other address field can be enabled with one metadata entry
- No Composer/NPM dependencies; works with the public photon.komoot.io or your self-hosted Photon instance

**Requirements:** EspoCRM 10.x, PHP 8.3+

**Download & docs:** https://github.com/gises/espocrm-address-autocomplete
(installable ZIP under Releases; AGPL-3.0, same license as EspoCRM)

Feedback and contributions welcome!

[crmscot]

This looks like a very useful extension and many thanks for your hard work.

I've tested it with a fresh install of EspoCRM V10.0.3 for UK addresses (Country set to GB) and noticed the following errors:-

1) UK street addresses take the format "housenumber street" but the lookup puts the result in EspoCRM as "street housenumber".

I had a quick look at the extension code and seem able to fix this by changing line 87 in ResultMapper.php to "return $houseNumber !== null ? "{$houseNumber} {$street}" : $street;"
Not sure if this is the correct way to fix this but it does produce the correct result.

2) The returned address has incorrect data for State (or County as it is known in the UK). For example, searching for "29/2 Hardengreen Industrial Estate" finds the correct address but the State (County) field is "Scotland". It should be "Midlothian"

I've not been able to correct this but don't think it's a limitation in the Photon database. I've tried a search in demo mode (using Google AI) and it returns the correct address with State (County) showing as "Midlothian".

Perhaps you can investigate these 2 issues and provide a solution.

[gim]

Thanks a lot for testing with UK addresses and for the detailed report – both points were spot on, and both are fixed in **v1.5.2**, just released:

https://github.com/gises/espocrm-address-autocomplete/releases/tag/v1.5.2

**1) House number position.** You're right that UK addresses put the number first. Your suggested change in ResultMapper.php works for the UK, but it would flip the order for every country – in the DACH region (and most of continental Europe) the convention is "Bahnhofstrasse 8", not "8 Bahnhofstrasse". Interestingly, Photon's own demo site hardcodes number-first for all countries, so it happens to look right for the UK and wrong for continental Europe – the API itself only returns raw components and leaves formatting to the client.

The fix is therefore country-aware: the extension now formats number-first for 40 countries following the anglophone and francophone postal tradition (GB, IE, US, CA, AU, NZ, IN, SG, HK, FR, LU, and others), and street-first everywhere else. The decision is made per suggestion, based on the country of the address that was found – not on the user's locale. So capturing a Swiss address still yields "Bahnhofstrasse 8", while your example now correctly yields "29/2 Hardengreen Industrial Estate". If a country's convention is wrong or missing, it's a one-line change – just let me know.

**2) State/County.** Confirmed, and it's not a Photon data limitation: Photon returns *both* properties for your example – `state: "Scotland"` and `county: "Midlothian"` – and the extension simply picked `state`. For GB and IE it now fills the State field from `county` (falling back to `state` when no county is returned), so your search yields Street "29/2 Hardengreen Industrial Estate", City "Dalkeith", County "Midlothian".

Your Hardengreen example is now part of the test suite (the PHP and Node mappers are tested against the same fixtures), so this won't regress. Thanks again – exactly the kind of feedback that makes the extension useful outside the region it was born in!