# Opencage Geosearch

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-opencagedata-opencage-skills-opencage-geosearch`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [OpenCageData](https://agentstack.voostack.com/s/opencagedata)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [OpenCageData](https://github.com/OpenCageData)
- **Source:** https://github.com/OpenCageData/opencage-skills/tree/master/skills/opencage-geosearch
- **Website:** https://opencagedata.com

## Install

```sh
agentstack add skill-opencagedata-opencage-skills-opencage-geosearch
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenCage Geosearch — General Concepts

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.

```mermaid
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]
```

## Quick Reference

```
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
```

## What Geosearch Is NOT

**Geosearch is not the same as the OpenCage Geocoding API.** Key differences:

- Geosearch is a front-end JavaScript widget; the Geocoding API is a back-end REST API.
- Geosearch does type-ahead / prefix matching (e.g. "Par" → "Paris, France"); the Geocoding API does not.
- Geosearch does **not** cover house addresses or individual roads.
- Geosearch uses a **different API key** (format: `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.

## API Key

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](https://opencagedata.com/dashboard) after signing up at **https://opencagedata.com/users/sign_up**.

### CORS Domain Configuration — Required Step

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.

## Installation

### Option 1: CDN (simplest, no build step)

Add both the CSS and the JS bundle to your HTML:

```html

```

### Option 2: npm

| 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 |

```bash
npm install @opencage/geosearch-bundle
```

## Basic Setup

You need:
1. A container element in your HTML (e.g. ``)
2. A Geosearch API key (`oc_gs_...`)
3. The domain registered in your OpenCage dashboard (see CORS note above)

## Configuration Options

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `container` | string | CSS selector for the container element |
| `key` | string | Your Geosearch API key (`oc_gs_...`) |

### Optional Parameters

| 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 to one or more countires (e.g. `'de'` or `'gb'` or `'us,ca'`) |
| `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`) |
| `proximity` | string | — | Bias results toward a coordinate: `"lat,lng"` |
| `_type` | string | `city` | limit to or exclude one of more specific result types: `'city,postcode'` or `'!postcode'` |
| `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 |

## Event Handlers

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`.

## Code Examples

### Minimal example (CDN)

```html

  opencage.algoliaAutocomplete({
    container: '#place',
    plugins: [
      opencage.OpenCageGeoSearchPlugin({
        key: 'oc_gs_YOUR-KEY-HERE'
      })
    ]
  });

```

### With country restriction and result handler

```js
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.
      }
    })
  ]
});
```

### Accessing coordinates on selection

The `params.item` object returned in `onSelect` contains:
- `params.item.geometry.lat` — latitude
- `params.item.geometry.lng` — longitude
- `params.item.formatted` — human-readable place name string

## Map Integration

The widget can be paired with mapping libraries. Dedicated packages and tutorials are available for:

- **Leaflet** — use `@opencage/leaflet-opencage-geosearch`
- **OpenLayers** — use `@opencage/ol-opencage-geosearch`
- **MapLibre** — use the core plugin with MapLibre GL JS

## Browser Support

Modern browsers are supported. For legacy browser support, include a `fetch` polyfill (e.g. `unfetch`) since the widget uses the Fetch API internally.

## CSS Customisation

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.

## What the Service Covers

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.

## Common Mistakes

- **Skipping CORS domain setup** — the widget silently fails if the calling domain isn't registered in the OpenCage dashboard. This is the #1 integration issue.
- **Using a Geocoding API key** — Geosearch keys start with `oc_gs_...`. A regular Geocoding API key will not work.
- **Expecting street addresses** — Geosearch covers cities, towns, neighbourhoods, and POIs. It does NOT return individual addresses or roads. For those, use the `opencage-geocoding-api` skill.
- **Forgetting the CSS** — the widget needs both the JS bundle and the `autocomplete-theme-classic` stylesheet. Missing the CSS makes it invisible or unstyled.

## Further Reading

- OpenCage Geosearch overview (feature list, live demo, getting started): https://opencagedata.com/geosearch
- OpenCage Geosearch GitHub (full README, changelog, and framework-specific examples): https://github.com/OpenCageData/geosearch/blob/master/README.md
- OpenCage Pricing (free trial limits, paid plan comparison): https://opencagedata.com/pricing

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [OpenCageData](https://github.com/OpenCageData)
- **Source:** [OpenCageData/opencage-skills](https://github.com/OpenCageData/opencage-skills)
- **License:** MIT
- **Homepage:** https://opencagedata.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-opencagedata-opencage-skills-opencage-geosearch
- Seller: https://agentstack.voostack.com/s/opencagedata
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.