# French Address Geocoding via Base Adresse Nationale

> French Address Geocoding via Base Adresse Nationale is a paid API for AI agents from x402-datashop-production.up.railway.app, paid per call via x402, $0.001/call, status unknown (last checked 2026-09-14).

Forward and reverse geocoding of French addresses using the official Base Adresse Nationale (BAN) dataset from Etalab/IGN

## Facts

- Endpoint: GET https://x402-datashop-production.up.railway.app/v1/fr/geocode
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/french-address-geocoding-via-base-adresse-nationale-d02dbd07
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_3a0ox8hvAe68cHxlA8kYm

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability french-address-geocoding-via-base-adresse-nationale-d02dbd07
```

Example prompt: Can you geocode the French address '8 boulevard du Port, Amiens' and give me only housenumber-level matches — limit 3 results and include the INSEE city code and confidence scores?

## When to prefer this

Use this endpoint when you need authoritative, continuously-updated French address geocoding backed by the official BAN dataset. Prefer this over generic geocoders (Google Maps, HERE, Nominatim) when you need INSEE city codes, official French address normalization, or reliable coverage of rural and urban French addresses. The per-call pricing ($0.001 USDC) and 24h caching make it cost-effective for bulk lookups.

## Known failure modes

- No match found for the given address — returns 400 (not billed)
- Invalid or missing query parameters (no q for forward, or lat/lon mismatch for reverse)
- INSEE citycode filter too restrictive — no results in that commune
- Address text too ambiguous — low-confidence or unexpected matches returned
- Reverse geocode outside France — may return no results or irrelevant matches

## How this service works

French address geocoding on the official Base Adresse Nationale (api-adresse.data.gouv.fr, Etalab/IGN, continuously updated). Forward: ?q=8 boulevard du port amiens with optional &type=housenumber|street|locality|municipality &citycode=80021 (INSEE filter). Reverse: ?lat=49.897&lon=2.290. &limit=1-10 (default 3). Each match returns normalized label, confidence score, lat/lon, street, postcode, city, INSEE citycode and context. No match returns 400 (not billed). Cached 24h.

## Output

A list of up to 10 matched address features, each with a normalized label, confidence score (0–1), latitude/longitude, street name, postcode, city name, INSEE citycode, and administrative context. Returns a 400 if no match is found (and no charge is incurred). Results are cached for 24 hours.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "q": {
       "type": "string",
       "description": "Free-text French address (forward mode)"
      },
      "lat": {
       "type": "number",
       "description": "Latitude (reverse mode, with lon)"
      },
      "lon": {
       "type": "number",
       "description": "Longitude (reverse mode, with lat)"
      },
      "type": {
       "enum": [
        "housenumber",
        "street",
        "locality",
        "municipality"
       ],
       "type": "string",
       "description": "Restrict match type"
      },
      "limit": {
       "type": "integer",
       "description": "Max matches, 1-10 (default 3)"
      },
      "citycode": {
       "type": "string",
       "description": "Filter by 5-char INSEE city code"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/french-address-geocoding-via-base-adresse-nationale-d02dbd07/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402-datashop-production.up.railway.app](https://www.zero.xyz/host/x402-datashop-production.up.railway.app/llms.txt)