# French Communes Lookup (geo.api.gouv.fr)

> French Communes Lookup (geo.api.gouv.fr) 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-13).

Look up French communes by postal code, INSEE code, fuzzy name, or geographic coordinates, returning name, INSEE code, population, postal codes, département, région, and EPCI.

## Facts

- Endpoint: GET https://x402-datashop-production.up.railway.app/v1/fr/communes
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/french-communes-lookup-geo-api-gouv-fr-6d3bd926
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_fCKiryaRJrUKtYUC1lRmn

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-communes-lookup-geo-api-gouv-fr-6d3bd926
```

Example prompt: What is the INSEE code, population, and région for the commune with postal code 31700 in France?

## When to prefer this

Use this endpoint when you need authoritative French commune reference data including the postal-to-INSEE code mapping, which is the canonical join key for French territorial datasets. Prefer this over general geocoding APIs when you specifically need INSEE codes, EPCI identifiers, or French administrative hierarchy (département/région). Ideal for enriching addresses, validating French postal codes, or joining INSEE demographic datasets.

## Known failure modes

- No commune found matching the provided postal code, INSEE code, name, or coordinates — returns empty results array
- Invalid or malformed query parameter (e.g. non-numeric lat/lon) — may return 400 or empty results
- Point coordinates that fall outside France or in the sea return no matching commune
- Fuzzy name search with very ambiguous input may return unexpected communes
- Upstream geo.api.gouv.fr unavailability causes proxy errors

## How this service works

Official French administrative reference from geo.api.gouv.fr (INSEE/IGN data). Look up communes by ?cp=31700 (postal code), ?code=31056 (INSEE), ?nom=Blagnac (fuzzy name) or ?lat=43.63&lon=1.37 (commune containing a point). Returns up to 20 communes with name, INSEE code, population, postal codes, departement, region and EPCI. The postal-to-INSEE mapping is the pivot key for joining French territorial datasets. Cached 7 days.

## Output

Returns up to 20 matching communes, each with name, INSEE code, population, list of postal codes, département code and name, région code and name, and EPCI identifier. Response is cached for 7 days.

## 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": {
      "cp": {
       "type": "string",
       "description": "5-digit postal code, e.g. 31700"
      },
      "lat": {
       "type": "number",
       "description": "Latitude (with lon: commune containing the point)"
      },
      "lon": {
       "type": "number",
       "description": "Longitude (with lat)"
      },
      "nom": {
       "type": "string",
       "description": "Commune name, fuzzy search"
      },
      "code": {
       "type": "string",
       "description": "5-character INSEE commune code, e.g. 31056"
      }
     }
    }
   },
   "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-communes-lookup-geo-api-gouv-fr-6d3bd926/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)