Search completion

When the user is typing a partial French address and wants autocomplete suggestions — reach for API Adresse's /completion endpoint. Fast, lightweight type-ahead for interactive address entry, no auth required.

search-completion · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/search-completion. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/search-completion/SKILL.md.

When to use this skill

When the user is typing a partial French address and wants autocomplete suggestions — "8 Blvd du Port", "Rue de la Paix Par", "place de la Répub". This is the type-ahead endpoint: fast, lightweight, built for interactive address entry. For full geocoding with coordinates and structured components, use geocode-french-address instead. For reverse lookups (coordinates to address), this is the wrong skill.

Your best first call

curl "https://api-adresse.data.gouv.fr/completion?q=8+Boulevard+du+Port+Cergy"

No auth. No key. The q parameter takes whatever the user has typed so far. The response is intentionally lightweight compared to /search:

fulltext — completed address string (e.g. "8 Boulevard du Port, 95000 Cergy")
x, y — coordinates; x is longitude, y is latitude
street — matched street name
city, zipcode — commune and postal code
kind — address type: housenumber, street, city, etc.
classification — confidence ranking 1–7, where 7 is highest

Fallbacks (when the best call isn't enough)

Full geocoding with structured results → /search?q=... returns GeoJSON FeatureCollections with citycode (INSEE), district, context, and importance scores. Use when the user has confirmed the address and needs precise coordinates or administrative codes.
Reverse geocoding (coordinates to address) → /reverse?lat=...&lon=... finds the nearest address to a point. Use when the input is GPS coordinates, not text.

Pitfalls

/completion returns {status, results} with flat objects — not GeoJSON. The field names differ from /search: fulltext vs label, x/y vs geometry.coordinates. Do not reuse a /search parser for /completion responses.
x is longitude and y is latitude here, while /search uses [lon, lat] in GeoJSON, and most mapping libraries expect [lat, lon]. Three different conventions across two endpoints — pick one and document it.
/completion is tuned for prefix matching, not fuzzy search. If the user's input has typos, /search handles approximate matches better.

One-line summary for the user

I can autocomplete partial French addresses as you type — returning lightweight suggestions from the official API Adresse service, no auth needed.

APIs this skill uses

API Adresse · primary · verified

French national address geocoding API. Provides search (address to coordinates), reverse geocoding (coordinates to address), and autocomplete functionality. Powered by the Base Adresse Nationale (BAN).

Generated from

API Adresse tutorial Getting Started with API Adresse

SKILL.md source (frontmatter + body)

---
name: search-completion
description: When the user is typing a partial French address and wants autocomplete suggestions — reach for API Adresse's /completion endpoint. Fast, lightweight type-ahead for interactive address entry, no auth required.
---

## When to use this skill

When the user is typing a partial French address and wants autocomplete suggestions — "8 Blvd du Port", "Rue de la Paix Par", "place de la Répub". This is the type-ahead endpoint: fast, lightweight, built for interactive address entry. For full geocoding with coordinates and structured components, use `geocode-french-address` instead. For reverse lookups (coordinates to address), this is the wrong skill.

## Your best first call

```bash
curl "https://api-adresse.data.gouv.fr/completion?q=8+Boulevard+du+Port+Cergy"
```

No auth. No key. The `q` parameter takes whatever the user has typed so far. The response is intentionally lightweight compared to `/search`:

- `fulltext` — completed address string (e.g. "8 Boulevard du Port, 95000 Cergy")
- `x`, `y` — coordinates; `x` is longitude, `y` is latitude
- `street` — matched street name
- `city`, `zipcode` — commune and postal code
- `kind` — address type: `housenumber`, `street`, `city`, etc.
- `classification` — confidence ranking 1–7, where 7 is highest

## Fallbacks (when the best call isn't enough)

- **Full geocoding with structured results** → `/search?q=...` returns GeoJSON FeatureCollections with `citycode` (INSEE), `district`, `context`, and `importance` scores. Use when the user has confirmed the address and needs precise coordinates or administrative codes.
- **Reverse geocoding (coordinates to address)** → `/reverse?lat=...&lon=...` finds the nearest address to a point. Use when the input is GPS coordinates, not text.

## Pitfalls

- `/completion` returns `{status, results}` with flat objects — not GeoJSON. The field names differ from `/search`: `fulltext` vs `label`, `x`/`y` vs `geometry.coordinates`. Do not reuse a `/search` parser for `/completion` responses.
- `x` is longitude and `y` is latitude here, while `/search` uses `[lon, lat]` in GeoJSON, and most mapping libraries expect `[lat, lon]`. Three different conventions across two endpoints — pick one and document it.
- `/completion` is tuned for prefix matching, not fuzzy search. If the user's input has typos, `/search` handles approximate matches better.

## One-line summary for the user

I can autocomplete partial French addresses as you type — returning lightweight suggestions from the official API Adresse service, no auth needed.

« Back to all skills