{ "openapi": "3.0.1", "info": { "title": "France Address Geocoder API (Géocodage BAN): INSEE, GPS", "description": "Geocode French addresses in bulk with the official BAN (IGN Géoplateforme): normalized address, match score, INSEE code, postcode, GPS and Lambert 93. Reverse geocoding too. No API key, no login. MCP-ready for AI agents. Pay per result, not found is free. $0.30 per 1,000 addresses", "version": "0.1", "x-build-id": "UrernnHM9xHHUtY2T" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/actose~france-address-geocoder/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-actose-france-address-geocoder", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/actose~france-address-geocoder/runs": { "post": { "operationId": "runs-sync-actose-france-address-geocoder", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/actose~france-address-geocoder/run-sync": { "post": { "operationId": "run-sync-actose-france-address-geocoder", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "addresses": { "title": "Addresses to geocode", "type": "array", "description": "One French postal address per line, free text (e.g. \"1 place du Capitole 31000 Toulouse\"). Adding the postcode or city improves accuracy. Duplicates are processed and charged once.", "items": { "type": "string" } }, "coordinates": { "title": "Coordinates to reverse geocode", "type": "array", "description": "One \"latitude,longitude\" pair per line in WGS84 decimal degrees (e.g. \"43.6045,1.4442\"). Returns the nearest official address with its distance in meters.", "items": { "type": "string" } }, "minScore": { "title": "Minimum match score", "minimum": 0, "maximum": 1, "type": "number", "description": "Forward geocoding only. Matches below this BAN score (0 to 1) are returned as \"notFound\" and not charged. 0.7 rejects invented addresses while keeping common typos and abbreviations (\"av\", \"bd\").", "default": 0.7 }, "maxResultsPerAddress": { "title": "Candidates per address", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of candidates returned per input (1 to 10). The best one has rank 1. Only one event is charged per input, whatever this number.", "default": 1 }, "resultType": { "title": "Result type", "enum": [ "any", "housenumber", "street", "locality", "municipality" ], "type": "string", "description": "Restrict results to one level of precision. Leave empty to get the best match at any level.", "default": "any" }, "postcode": { "title": "Filter by postcode", "type": "string", "description": "Optional. Only return addresses with this postcode (e.g. \"31000\"). Applies to every forward query of the run." }, "inseeCode": { "title": "Filter by INSEE municipality code", "type": "string", "description": "Optional. Only return addresses in this municipality, by its INSEE code (e.g. \"31555\" for Toulouse, \"75056\" for Paris). Applies to every forward query of the run." }, "includeNotFound": { "title": "Include not found and invalid inputs", "type": "boolean", "description": "Adds a free row with status \"notFound\" or \"error\" for each input that has no result, so every input line can be matched back in your spreadsheet. These rows are never charged.", "default": true }, "service": { "title": "Official service", "enum": [ "geoplateforme", "api-adresse" ], "type": "string", "description": "Which official BAN endpoint to query first. The other one is used automatically if the first is down.", "default": "geoplateforme" }, "maxConcurrency": { "title": "Parallel requests", "minimum": 1, "maximum": 20, "type": "integer", "description": "Requests in flight at the same time. The run never exceeds 25 requests per second, below the official limit of 50 per second.", "default": 10 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }