Napsal jsem si kdysi malý plugin, který na pokladně e-shopu našeptává adresy z Mapy.com – vyberete ulici a rovnou se doplní město, PSČ i země. Fungoval dobře, ale byl to plugin „jen pro mě“: nastavený natvrdo v kódu a ušitý na konkrétní klientské weby. Teď jsem z něj s pomocí Claude Code udělal univerzální plugin, který si kdokoli nainstaluje a nakliká v administraci.
Tady je, jak to vzniklo – a rovnou i návod, jak si zařídit klíč k Mapy.com. Spoiler: bez kreditky.
Jak to začalo – pokladna
Prvotní verze řešila jednu věc: našeptávání adresy na WooCommerce pokladně. Zákazník začne psát ulici, vybere z nabídky Mapy.com a formulář se sám doplní – ulice, město, PSČ, země. Míň překlepů a hlavně jasně a správně strukturované adresy – to ocení každé napojení na API externích dopravců, které v různých projektech řeším.
Pak přišel Contact Form 7
Pro jednoho klienta přibyl požadavek: stejný našeptávač i do kontaktního formuláře (Contact Form 7), ne jen do pokladny. Přidal jsem tedy adaptér pro CF7. Jenže mapování polí – které pole je ulice, které město, PSČ, země – bylo zase napevno svázané s konkrétním formulářem na daném webu.
Háček: byl to plugin jen pro mě
Fungovalo to, ale mělo to jednu vadu. Všechno podstatné – API klíč, kde se má našeptávat, názvy polí ve formuláři – bylo zadrátované v kódu. Každý nový web se musel nastavit přesně podle kódu, případně kód poupravit.
Rozhodl jsem se to změnit (s Claude Code)
Řekl jsem si, že z toho udělám plugin, který dám ven – veřejný, univerzální a celý konfigurovatelný z administrace. S Claude Code jsem:
- vytáhl veškeré nastavení z kódu do jedné stránky v administraci,
- přidal přepínače, kde se má našeptávat (WooCommerce / Contact Form 7),
- udělal volbu zemí, ze kterých se adresy nabízejí,
- a hlavně nastavitelné mapování polí pro CF7 – globálně i pro konkrétní formulář zvlášť.
Přibyla i automatická aktualizace z GitHub Releases. Podstatné ale je, že plugin je teď použitelný i pro lidi, co do kódu sahat nechtějí.
Proč Mapy.com a ne Google
Našeptávač jede na suggest API Mapy.com. Vůči Google Places má pro tenhle účel jednu velkou výhodu hned na začátku: registrace do developer.mapy.com po vás nechce platební kartu. U Google Cloudu bez založeného fakturačního účtu s kartou API vůbec nerozjedete; u Mapy.com se prostě zaregistrujete a máte klíč.
A bezplatný tarif je štědrý. Na základním (free) tarifu dostanete 250 000 kreditů měsíčně a placená spotřeba je ve výchozím stavu zakázaná – takže se vám nemůže stát, že přijde nečekaná faktura. Když kredity dojdou, API prostě přestane odpovídat, dokud se limit další měsíc neobnoví. Na běžné našeptávání na jednom e-shopu je čtvrt milionu kreditů řádově víc, než spotřebujete.
Pozn.: Ceník a výše kreditů se pochopitelně můžou v čase měnit – hodnoty výše jsou stav v době psaní článku. Aktuální podmínky vždy najdete ve svém účtu.
Návod: jak si zařídit klíč na developer.mapy.com
Krok za krokem:
1. Registrace a projekt. Přihlaste se na developer.mapy.com (účtem Seznam) a v sekci Projekty založte nový projekt (tlačítko „Vytvořit nový projekt“). V přehledu projektu pak vidíte, že je volání API povolené, a průběžnou spotřebu kreditů.
2. API klíč. V projektu máte v sekci „API klíče“ rovnou výchozí klíč. Ten si zkopírujte.
3. Omezte klíč – tohle nepřeskakujte. Klíč se používá přímo v prohlížeči, takže je vidět ve zdrojáku stránky. Tak to Mapy.com mají navržené a je to v pořádku, ale znamená to, že by ho někdo mohl opsat a použít na cizím webu (a vyčerpat vám kredit). Proto ho v Nastavení klíče → Omezení API klíče omezte. Na výběr jsou tři typy:
- Referery (HTTP referer) – typicky doména vašeho webu. Pro našeptávač běžící v prohlížeči je to nejběžnější a nejrozumnější volba.
- IP adresy – hodí se spíš pro serverová volání, kde referer chybí.
- User agenti – doplňkově.
Pro web na jedné doméně tedy nejspíš sáhnete po omezení podle refereru na doménu webu.
4. Vložte klíč do pluginu. Ve WordPressu jděte do Nastavení → LH Seznam.cz autocomplete a klíč vložte do pole „API klíč Mapy.cz“.
Nastavení pluginu
Celé nastavení je na jediné stránce v Nastavení → LH Seznam.cz autocomplete:
- API klíč Mapy.cz – bez něj se plugin nikde nenačte.
- Kde našeptávat – přepínače pro WooCommerce (klasická i bloková pokladna) a pro Contact Form 7. Skripty pluginu se načtou jen tam, kde je našeptávač zapnutý.
- Země pro našeptávání – Česko, Slovensko, Polsko, Německo, Rakousko, Maďarsko. Výchozí je Česko a Slovensko; když nezaškrtnete žádnou zemi, hledá se ve všech podporovaných.
- Výchozí pole pro CF7 – názvy (
name) polí z CF7 tagů: ulice, město, PSČ, země. Pole „ulice“ je povinné, protože spouští našeptávání; ostatní jsou volitelná. U konkrétního formuláře jde mapování přepsat přímo v jeho editoru na záložce „Mapy.cz našeptávač“.
Nastavení přímo u formuláře (Contact Form 7)
Globální mapování polí stačí, dokud mají formuláře stejné názvy polí. Když ne, jde ho přepsat u konkrétního formuláře. V editoru CF7 přibude záložka „Mapy.cz našeptávač“ a na ní nastavíte jen pro tenhle jeden formulář:
- Našeptávač – zapnout nebo vypnout jen pro tento formulář, nebo zdědit z globálního nastavení pluginu.
- Ulice, Město, PSČ, Země – u každého pole buď vyberete konkrétní pole formuláře, necháte Globální default, nebo dáte — nepoužívat —.
Nabídka rovnou obsahuje pole, která formulář opravdu má (podle jeho tagů), takže se v názvu nepřeklepnete. Ulice je i tady povinná – spouští našeptávání.
Kde to najít
Plugin je na GitHubu: github.com/luboshilgert/lh-seznamcz-autocomplete. Není na wordpress.org, ale sám se aktualizuje z GitHub Releases (přes Plugin Update Checker), takže se update nabídne standardně v administraci.
Z pluginu ušitého jednomu klientovi je teď nástroj, který si nasadí kdokoli – a to hlavní kouzlo bylo přesunout konfiguraci z kódu do administrace. Když k tomu přičtu, že Mapy.com nechtějí kreditku a dávají štědrý free tier, je to pro české a slovenské weby docela příjemná alternativa Google Places, který bez kreditky nerozjedete.