Publisher utility
Embeddable Postal Search Widget
Add a lightweight, attributed search box with a constrained origin-bound widget key.
Installation
<div data-zcg-widget data-key="YOUR_WIDGET_KEY" data-country="US"></div>
<script src="https://zipcodeglobe.com/public/js/embed.js" defer></script>Create a widget key in admin, add each permitted origin, and keep the visible “Powered by ZipCodeGlobe” attribution. The browser key is intentionally constrained and cannot access bulk or server endpoints.
What the widget provides
The script adds a small postal search form to a host page and sends suggestions to a dedicated constrained endpoint. Results link back to ZipCodeGlobe, where the user can review the complete source record, multiple place matches and attribution. The widget does not expose bulk validation, admin functions or unrestricted server API access.
The host page remains responsible for its own layout, privacy notice and accessibility testing. ZipCodeGlobe’s script uses semantic form controls and an announced result list, but surrounding styles and scripts can still affect usability.
Create an origin-bound widget key
In admin, create a key with type “widget” and list every exact allowed origin, including scheme and hostname. A browser request without an allowed Origin header is rejected. Do not reuse a server key in public HTML, and do not configure a wildcard origin. Revoke and replace a key that appears on an unauthorised site.
The full secret is shown once. The database stores only a strong hash and short prefix. Daily usage counters and expiry provide additional control, while rate limits protect the public endpoint from abuse.
Install without a build system
Add the widget container, key and optional ISO2 country scope, then load the self-hosted script with defer. The script derives the API base from its own URL, so staging and production copies can operate without hard-coded third-party hosts. Keep the visible attribution link. Do not copy or alter the script to conceal its source.
The widget is progressive enhancement for the host site. Provide a normal link to ZipCodeGlobe as a fallback for visitors with JavaScript disabled or when the endpoint is temporarily unavailable.
Country scoping and search quality
Set data-country when the host page serves one destination country. Country context reduces ambiguity because identical codes and place names can appear in different systems. For a global form, let the user select country visibly before launching postal suggestions rather than guessing silently from IP location.
Suggestions are capped and intended to guide the user, not certify a complete address. The linked result may contain several places for one code. Host applications should let the user confirm rather than automatically filling the first response.
CORS and browser security
The widget endpoint returns cross-origin access only for the exact origin configured on the widget key. Server-to-server API endpoints do not need permissive browser CORS. This separation reduces the risk that a public key becomes an open proxy for unrelated requests.
Use HTTPS on both sites. Keep the script source fixed to the trusted ZipCodeGlobe domain or your verified deployment. A Content Security Policy on the host may need to allow that script and connection origin explicitly.
Privacy and analytics
Do not attach customer names or full addresses to the query. A place or postal-code suggestion usually needs only a short search string and optional country. The host’s privacy notice should explain the external request when applicable. ZipCodeGlobe avoids sending raw search text to general analytics and retains only bounded operational information under configured policies.
If the widget is used in checkout, the host remains responsible for lawful processing, consent where required and retention of the completed address.
Performance and resilience
The script is small, self-hosted and framework-free. It loads after HTML parsing and does not render an entire postal dataset in the browser. Requests are bounded by API quotas and result caps. A failed request shows an error in the widget rather than breaking the host page.
Version static assets so browser and LiteSpeed caches do not hide a deployed fix. Test keyboard input, mobile widths, slow networks and a revoked key before production launch.
Appropriate uses
The widget works well for country information pages, shipping resources, travel tools and business forms that need a quick path into postal research. It should not be presented as an official government or postal-operator widget. Keep the attribution and source limitations visible on the destination result.
For high-volume validation, use a server API key and the documented endpoints. The browser widget is deliberately limited so visitor engagement does not weaken API security or data trust.