> ## Documentation Index > Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt > Use this file to discover all available pages before exploring further. # Batch Geocode > Batch geocode a list of addresses in a single request. Each item can be free text or structured address components. Results are returned per-item with the original index preserved, so failed items don't break the batch. Use this for spreadsheet imports, database enrichment, or any bulk geocoding task. ## OpenAPI ````yaml POST /v1/geocoding/batch openapi: 3.1.0 info: title: Footstep API description: >- Terrain-intelligent routing, geocoding, elevation, and spatial analysis. Every routing response includes terrain analytics by default. Routing endpoints support two response formats: footstep (default, compact) and geojson (standard GeoJSON). version: 1.0.0 servers: - url: https://api.footstep.ai description: Production security: - apiKey: [] paths: /v1/geocoding/batch: post: tags: - Geocoding summary: Geocode up to 1,000 addresses in one request description: >- Batch geocode a list of addresses in a single request. Each item can be free text or structured address components. Results are returned per-item with the original index preserved, so failed items don't break the batch. Use this for spreadsheet imports, database enrichment, or any bulk geocoding task. operationId: geocodingBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GeocodingBatchRequest' examples: free_text: summary: Free-text batch value: items: - text: Buckingham Palace, London - text: Eiffel Tower, Paris - text: Colosseum, Rome structured: summary: Structured batch value: items: - address: 10 Downing Street locality: London country: GBR - address: 1600 Pennsylvania Ave locality: Washington region: DC country: USA responses: '200': description: Batch geocoding results content: application/json: schema: $ref: '#/components/schemas/GeocodingBatchResponse' examples: success: summary: Mixed results value: results: - index: 0 results: - coordinates: lat: 51.5014 lng: -0.1419 label: Buckingham Palace, London, England, United Kingdom name: Buckingham Palace country: United Kingdom country_code: GBR region: England locality: London confidence: 0.95 place_type: venue - index: 1 results: - coordinates: lat: 48.8584 lng: 2.2945 label: Eiffel Tower, Paris, Île-de-France, France name: Eiffel Tower country: France country_code: FRA region: Île-de-France locality: Paris confidence: 0.96 place_type: venue - index: 2 results: - coordinates: lat: 41.8902 lng: 12.4922 label: Colosseum, Rome, Lazio, Italy name: Colosseum country: Italy country_code: ITA region: Lazio locality: Rome confidence: 0.97 place_type: venue summary: total: 3 matched: 3 failed: 0 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Geocoding engine unavailable content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: GeocodingBatchRequest: type: object required: - items properties: items: type: array minItems: 1 maxItems: 1000 description: >- Addresses to geocode. Each item can use free text (text field) or structured components (address, locality, country, etc.). items: type: object properties: text: type: string description: Free-text address or place name address: type: string description: House number and street neighbourhood: type: string locality: type: string description: City or town county: type: string region: type: string description: State, province, or region postalcode: type: string country: type: string description: ISO 3166-1 alpha-3 country code size: type: integer minimum: 1 maximum: 10 default: 1 description: Maximum results per item GeocodingBatchResponse: type: object required: - results - summary properties: results: type: array items: type: object required: - index - results properties: index: type: integer description: Original item index (0-based) results: type: array items: $ref: '#/components/schemas/GeocodingResult' error: type: string description: Error message if this item failed summary: type: object required: - total - matched - failed properties: total: type: integer description: Total items submitted matched: type: integer description: Items with at least one result failed: type: integer description: Items that returned an error Error: type: object required: - error - message properties: error: type: string message: type: string GeocodingResult: type: object required: - coordinates - label - name - confidence - place_type properties: coordinates: $ref: '#/components/schemas/GeocodingCoordinate' label: type: string description: Full human-readable label (e.g. 'London, England, United Kingdom') name: type: string description: Short name of the place country: type: string description: Country name country_code: type: string description: ISO 3166-1 alpha-3 country code region: type: string description: Region/state/province county: type: string description: County/district locality: type: string description: City/town neighbourhood: type: string description: Neighbourhood/suburb confidence: type: number minimum: 0 maximum: 1 description: Result confidence score (0-1) place_type: type: string description: 'Place type: venue, address, street, locality, region, country' GeocodingCoordinate: type: object required: - lat - lng properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Footstep API key ````