From opencage
Use when the user needs geographic place autosuggest or autocomplete on a web page, or mentions "geosearch", "place autocomplete", "OpenCage widget", "oc_gs_ key", or "geographic autosuggest". Also use when integrating a location search widget with Leaflet, OpenLayers, or MapLibre.
How this skill is triggered — by the user, by Claude, or both
Slash command
/opencage:opencage-geosearchThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
OpenCage Geosearch is a **JavaScript widget** that provides geographic autosuggest/autocomplete functionality for forms. It converts partial text input into place names — countries, states, regions, cities, towns, villages, and neighbourhoods. It is built on top of Algolia's Autocomplete library.
OpenCage Geosearch is a JavaScript widget that provides geographic autosuggest/autocomplete functionality for forms. It converts partial text input into place names — countries, states, regions, cities, towns, villages, and neighbourhoods. It is built on top of Algolia's Autocomplete library.
graph TD
A{User typing partial text\nin a search box?}
A -- yes --> B[Use this skill\nopenpage-geosearch]
A -- no --> C{Need street addresses\nor coordinates?}
C -- yes --> D[Use opencage-geocoding-api skill\nback-end REST API]
C -- no --> E[Neither skill applies]
Type: Front-end JavaScript widget (not a REST API)
Key: oc_gs_... (different from Geocoding API key)
Package: @opencage/geosearch-bundle (CDN or npm)
Setup: opencage.algoliaAutocomplete({ container, plugins: [OpenCageGeoSearchPlugin({ key })] })
Coords: params.item.geometry.lat / .lng (in onSelect handler)
CORS: MUST register domain in OpenCage dashboard before use
Covers: Countries, cities, towns, villages, neighbourhoods — NOT street addresses or postcodes
Geosearch is not the same as the OpenCage Geocoding API. Key differences:
oc_gs_...); a Geocoding API key will not work here.If the task requires converting a complete address or coordinates server-side, use the opencage-geocoding-api skill instead.
Geosearch uses its own API key, distinct from the Geocoding API key. The key format is oc_gs_....
Obtain a key from the OpenCage dashboard after signing up at https://opencagedata.com/users/sign_up.
Before the widget will work in a browser, you must add the domain(s) it will be called from to the allowed list in your OpenCage account dashboard. Requests from unlisted domains will be blocked. This is a common integration mistake — do not skip it.
Add both the CSS and the JS bundle to your HTML:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@opencage/geosearch-bundle/dist/css/autocomplete-theme-classic.min.css" />
<script src="https://cdn.jsdelivr.net/npm/@opencage/geosearch-bundle"></script>
| Package | Use case |
|---|---|
@opencage/geosearch-bundle | Bundled version including Algolia Autocomplete — easiest to use |
@opencage/geosearch-core | Core plugin only; bring your own Algolia Autocomplete dependency |
@opencage/leaflet-opencage-geosearch | Leaflet map integration |
@opencage/ol-opencage-geosearch | OpenLayers map integration |
npm install @opencage/geosearch-bundle
You need:
<div id="place"></div>)oc_gs_...)| Parameter | Type | Description |
|---|---|---|
container | string | CSS selector for the container element |
key | string | Your Geosearch API key (oc_gs_...) |
| Parameter | Type | Default | Description |
|---|---|---|---|
bounds | string | — | Restrict results to a bounding box: "min_lon,min_lat,max_lon,max_lat" |
countrycode | string | — | ISO 3166-1 Alpha-2 country code to restrict results (e.g. 'de', 'gb') |
proximity | string | — | Bias results toward a coordinate: "lat,lng" |
language | string | 'en' | Two-letter language code for results: de, en, es, fr, it, pt |
limit | number | 5 | Maximum number of results shown (max: 10) |
debounce | number | 300 | Milliseconds to wait after user stops typing before sending a request |
noResults | string | "No results." | Message displayed when the API returns no matches |
Pass event handlers as the second argument to OpenCageGeoSearchPlugin():
| Handler | When it fires |
|---|---|
onSelect(params) | User clicks or keyboards to a result |
onActive(params) | A result becomes the active/highlighted item |
onSubmit(params) | The form is submitted |
Each handler receives a params object containing state, event, item, and setter functions. The selected place's coordinates are at params.item.geometry.lat and params.item.geometry.lng.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@opencage/geosearch-bundle/dist/css/autocomplete-theme-classic.min.css" />
<script src="https://cdn.jsdelivr.net/npm/@opencage/geosearch-bundle"></script>
<div id="place"></div>
<script>
opencage.algoliaAutocomplete({
container: '#place',
plugins: [
opencage.OpenCageGeoSearchPlugin({
key: 'oc_gs_YOUR-KEY-HERE'
})
]
});
</script>
opencage.algoliaAutocomplete({
container: '#place',
plugins: [
opencage.OpenCageGeoSearchPlugin({
key: 'oc_gs_YOUR-KEY-HERE',
countrycode: 'de',
language: 'de',
limit: 3
}, {
onSelect: (params) => {
const { lat, lng } = params.item.geometry;
console.log('Selected coordinates:', lat, lng);
// e.g. populate hidden form fields, pan a map, etc.
}
})
]
});
The params.item object returned in onSelect contains:
params.item.geometry.lat — latitudeparams.item.geometry.lng — longitudeparams.item.formatted — human-readable place name stringThe widget can be paired with mapping libraries. Dedicated packages and tutorials are available for:
@opencage/leaflet-opencage-geosearch@opencage/ol-opencage-geosearchModern browsers are supported. For legacy browser support, include a fetch polyfill (e.g. unfetch) since the widget uses the Fetch API internally.
The widget ships with Algolia's autocomplete-theme-classic stylesheet. Appearance can be customised by overriding the CSS custom properties (variables) defined in that theme.
Geosearch returns results for: countries, states/provinces, regions, cities, towns, villages, suburbs/neighbourhoods, postcodes (for most countries), and some points of interest.
It does not return: individual street addresses or road names.
oc_gs_.... A regular Geocoding API key will not work.opencage-geocoding-api skill.autocomplete-theme-classic stylesheet. Missing the CSS makes it invisible or unstyled.Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub opencagedata/opencage-skills --plugin opencage