openapi: 3.0.0
info:
  title: Batch Geocoding API
  description: When you need to transform a large number of addresses into geographic coordinates programmatically, you can use a Batch Geocoding API.
  version: 1.0.0
  contact:
    name: Geoapify
    url: https://geoapify.com
    email: info@geoapify.com
  license:
    name: MIT
    url: https://opensource.org/license/mit
servers:
  - url: https://api.geoapify.com/v1
    description: Primary Geoapify API endpoint

tags:
  - name: Batch Geocoding API
    description: Allows geocoding multiple addresses or coordinates in a single request.

paths:
  # Batch Geocoding API
  /batch/geocode/search:
    post:
      tags:
        - Batch Geocoding API
      summary: Create a new forward batch geocoding job
      description: Submits a batch of addresses to be geocoded, returning a job ID for retrieving results once the process is complete.
      operationId: createForwardBatchGeocodingJob
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Geoapify API key to authenticate the request. You can sign up and obtain an API key for free at [https://myprojects.geoapify.com/](https://myprojects.geoapify.com/). The Free plan includes up to 3,000 requests per day.
          schema:
            type: string
            example: "YOUR_API_KEY"
        - name: type
          in: query
          required: false
          description: |
            Defines the location type to be searched. Available types include:

            - `country`: Search for countries.
            - `state`: Search for states or regions.
            - `city`: Search for cities or towns.
            - `postcode`: Search for postal codes.
            - `street`: Search for specific streets.
            - `amenity`: Search for points of interest (e.g., schools, parks, etc.).
            - `locality`: Search for administrative areas, which can include postcodes, districts, cities, counties, and states.
          schema:
            type: string
            enum: [ country, state, city, postcode, street, amenity ]
        - name: lang
          in: query
          required: false
          description: Result language in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format (e.g., 'en' for English).
          schema:
            type: string
            example: en
        - name: filter
          in: query
          required: false
          description: |
            Refine your batch geocoding results by applying specific geographic filters. These filters help narrow down the geocoding results based on geographic areas:

            - **By circle**:  
              Use `circle:lon,lat,radiusMeters` to limit the results to places within a circular area defined by longitude, latitude, and radius in meters.  
              Example: `filter=circle:-87.770231,41.878968,5000`
              
            - **By rectangle**:  
              Use `rect:lon1,lat1,lon2,lat2` to limit results to a rectangular area, defined by two points (longitude and latitude) representing the southwest and northeast corners.  
              Example: `filter=rect:-89.097540,39.668983,-88.399274,40.383412`
              
            - **By country**:  
              Use a comma-separated list of ISO 3166-1 Alpha-2 country codes in lowercase to restrict results to specific countries. Use `'auto'` to detect the country by IP address, or `'none'` to skip country filtering.  
              Example: `filter=countrycode:de,es,fr`
              
            - **By place**:  
              Use `place:placeId` to restrict the results to a specific boundary (city, district, postcode, etc.), using the `place_id` from a previous geocoding, reverse geocoding, or boundary lookup.  
              Example: `filter=place:51f07665660fc4024059dc0a96dfac6c...`
          schema:
            type: string
        - name: bias
          in: query
          required: false
          description: |
            Prioritize batch geocoding results based on proximity to specific geographic areas, such as a point, bounding box, or country, without limiting the search scope. This helps in obtaining closer results first:

            - **By circle**:  
              Use `circle:lon,lat,radiusMeters` to prioritize results from within a circular area, and then search globally.  
              Example: `bias=circle:-87.770231,41.878968,5000`
              
            - **By rectangle**:  
              Use `rect:lon1,lat1,lon2,lat2` to prioritize results from within a rectangular area (using two longitude and latitude points as southwest and northeast corners), and then search globally.  
              Example: `bias=rect:-89.097540,39.668983,-88.399274,40.383412`
              
            - **By country**:  
              Use comma-separated ISO 3166-1 Alpha-2 country codes in lowercase to prioritize results from the specified countries first. Use `'auto'` to detect the country by IP address, or `'none'` to skip country bias.  
              Example: `bias=countrycode:de,es,fr`
              
            - **By location**:  
              Use `proximity:lon,lat` to prioritize results based on distance from a specific longitude and latitude.  
              Example: `bias=proximity:41.2257145,52.971411`
          schema:
            type: string
            example: "rect:8.738507,-10.137391,63.042511,59.098366"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              description: A list of address strings to be geocoded in batch. Each item in the array should be a valid address or partial address to be processed by the geocoding service.
            example:
              - "668 Cedar St, San Carlos, CA 94070, United States of America"
              - "96 Rue Saint-Martin, 75004 Paris, France"
      responses:
        '202':
          description: Batch geocoding job successfully created. The response includes the job details, such as the unique job ID, current job status, and the URL to check the status or retrieve the results once processing is complete. **The job ID must be used to fetch the final geocoding results after the job has finished processing.**
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobResponse'
              example: |
                {
                  "id": "de5a2fb3e21a43a5915f7173fd711051",
                  "status": "pending",
                  "url": "https://api.geoapify.com/v1/batch/geocode/search?id=de5a2fb3e21a43a5915f7173fd711051&apiKey=YOUR_API_KEY"
                }
        '400':
          description: Bad Request. The input provided is invalid or improperly formatted. Please verify and correct your request parameters.
        '401':
          description: Unauthorized. The API key is missing, incorrect, or invalid. Please provide a valid API key to authenticate the request.
        '429':
          description: Request limit exceeded. Too many requests have been sent in a short period, surpassing the allowed rate limits.
        '500':
          description: Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. Please try again later or [contact support](mailto:info@geoapify.com) if the issue persists.

    get:
      tags: 
        - Batch Geocoding API
      summary: Retrieve batch geocoding job results
      description: Fetch the results of a batch forward geocoding job using the provided job ID. This allows you to obtain geographic coordinates (such as latitude and longitude) based on the provided address data after the batch job has been processed.
      operationId: getBatchGeocodingResults
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Geoapify API key to authenticate the request. You can sign up and obtain an API key for free at [https://myprojects.geoapify.com/](https://myprojects.geoapify.com/). The Free plan includes up to 3,000 requests per day.
          schema:
            type: string
            example: "YOUR_API_KEY"
        - name: id
          in: query
          required: true
          description: The unique job ID that was returned when the batch geocoding job was created. This ID is used to retrieve the results.
          schema:
            type: string
            example: '8f25c31e2179441ea103868fd9c3784d'
        - name: format
          in: query
          required: false
          description: The format in which to retrieve the results, either JSON or CSV.
          schema:
            type: string
            enum: [ json, csv ]
            example: json
      responses:
        '200':
          description: Successful response with batch geocoding results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchForwardGeocodingResults'
              example: |
                [
                  {
                    "query": {
                      "text": "668 Cedar St, San Carlos, CA 94070, United States of America",
                      "parsed": {
                        "housenumber": "668",
                        "street": "cedar st",
                        "postcode": "94070",
                        "city": "san carlos",
                        "state": "ca",
                        "country": "united states of america",
                        "expected_type": "building"
                      }
                    }
                  },
                  {
                    "query": {
                      "text": "96 Rue Saint-Martin, 75004 Paris, France",
                      "parsed": {
                        "housenumber": "96",
                        "street": "rue saint-martin",
                        "postcode": "75004",
                        "city": "paris",
                        "country": "france",
                        "expected_type": "building"
                      }
                    }
                  }
                ]
            text/csv:
              schema:
                type: string
                description: CSV format with headers and comma-separated values
              example: |
                "query.text","query.parsed.housenumber","query.parsed.street","query.parsed.postcode","query.parsed.city","query.parsed.state","query.parsed.country","query.parsed.expected_type"
                "668 Cedar St, San Carlos, CA 94070, United States of America","668","cedar st","94070","san carlos","ca","united states of america","building"
                "96 Rue Saint-Martin, 75004 Paris, France","96","rue saint-martin","75004","paris","","france","building"
        '202':
          description: The job is still processing.
        '400':
          description: Bad Request. The input provided is invalid or improperly formatted. Please verify and correct your request parameters.
        '401':
          description: Unauthorized. The API key is missing, incorrect, or invalid. Please provide a valid API key to authenticate the request.
        '429':
          description: Request limit exceeded. Too many requests have been sent in a short period, surpassing the allowed rate limits.
        '500':
          description: Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. Please try again later or [contact support](mailto:info@geoapify.com) if the issue persists.
  
  /batch/geocode/reverse:
    post:
      tags:
        - Batch Geocoding API
      summary: Create a new reverse batch geocoding job
      description: Submits a batch of latitude/longitude coordinates to be reverse geocoded, returning a job ID for retrieving results once the process is complete.
      operationId: createReverseBatchGeocodingJob
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Geoapify API key to authenticate the request. You can sign up and obtain an API key for free at [https://myprojects.geoapify.com/](https://myprojects.geoapify.com/). The Free plan includes up to 3,000 requests per day.
          schema:
            type: string
            example: "YOUR_API_KEY"
        - name: type
          in: query
          required: false
          description: |
            Defines the location type to be searched. Available types include:

            - `country`: Search for countries.
            - `state`: Search for states or regions.
            - `city`: Search for cities or towns.
            - `postcode`: Search for postal codes.
            - `street`: Search for specific streets.
            - `amenity`: Search for points of interest (e.g., schools, parks, etc.).
            - `locality`: Search for administrative areas, which can include postcodes, districts, cities, counties, and states.
          schema:
            type: string
            enum: [ country, state, city, postcode, street, amenity ]
        - name: lang
          in: query
          required: false
          description: Result language in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format (e.g., 'en' for English).
          schema:
            type: string
            example: en
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                oneOf:
                  - type: array
                    items:
                      type: number
                    description: Array of [longitude, latitude].
                    example: [ -122.263801, 37.502683 ]
                  - type: object
                    properties:
                      lon:
                        type: number
                      lat:
                        type: number
                    description: Object with 'lon' and 'lat' properties.
                    example: { "lon": -122.263801, "lat": 37.502683 }
              description: A list of latitude/longitude pairs for reverse geocoding.
      responses:
        '202':
          description: Job successfully created, returning job details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobResponse'
              example: |
                {
                  "id": "d8756e94f6ee42f7abdd9a0c99e6c9fd",
                  "status": "pending",
                  "url": "https://api.geoapify.com/v1/batch/geocode/reverse?id=d8756e94f6ee42f7abdd9a0c99e6c9fd&apiKey=YOUR_API_KEY"
                }
        '400':
          description: Bad Request. The input provided is invalid or improperly formatted. Please verify and correct your request parameters.
        '401':
          description: Unauthorized. The API key is missing, incorrect, or invalid. Please provide a valid API key to authenticate the request.
        '429':
          description: Request limit exceeded. Too many requests have been sent in a short period, surpassing the allowed rate limits.
        '500':
          description: Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. Please try again later or [contact support](mailto:info@geoapify.com) if the issue persists.

    get:
      tags:
        - Batch Geocoding API
      summary: Retrieve batch reverse geocoding job results
      description: Fetch the results of a batch reverse geocoding job using the provided job ID. This allows you to obtain geographic information (such as addresses) based on provided coordinates after the batch job has been processed.
      operationId: getBatchReverseGeocodingResults
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Geoapify API key to authenticate the request. You can sign up and obtain an API key for free at [https://myprojects.geoapify.com/](https://myprojects.geoapify.com/). The Free plan includes up to 3,000 requests per day.
          schema:
            type: string
            example: "YOUR_API_KEY"
        - name: id
          in: query
          required: true
          description: The unique job ID that was returned when the batch reverse geocoding job was created. This ID is used to retrieve the results.
          schema:
            type: string
            example: '8f25c31e2179441ea103868fd9c3784d'
        - name: format
          in: query
          required: false
          description: The format in which to retrieve the results, either JSON or CSV.
          schema:
            type: string
            enum: [ json, csv ]
            example: json
      responses:
        '200':
          description: Successful response with batch reverse geocoding results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchReverseGeocodingResults'
              example: |
                [
                  {
                    "query": {
                      "lon": -122.263801,
                      "lat": 37.502683,
                      "plus_code": "849VGP3P+3F"
                    },
                    "country_code": "us",
                    "housenumber": "656",
                    "street": "Cedar Street",
                    "country": "United States",
                    "county": "San Mateo County",
                    "datasource": {
                      "sourcename": "openaddresses",
                      "attribution": "© OpenAddresses contributors",
                      "license": "BSD-3-Clause License"
                    },
                    "postcode": "94070",
                    "state": "California",
                    "city": "San Carlos",
                    "state_code": "CA",
                    "lon": -122.263964,
                    "lat": 37.502693,
                    "distance": 14.421782254517026,
                    "result_type": "building",
                    "formatted": "656 Cedar Street, San Carlos, CA 94070, United States of America",
                    "address_line1": "656 Cedar Street",
                    "address_line2": "San Carlos, CA 94070, United States of America",
                    "timezone": {
                      "name": "America/Los_Angeles",
                      "offset_STD": "-08:00",
                      "offset_STD_seconds": -28800,
                      "offset_DST": "-07:00",
                      "offset_DST_seconds": -25200,
                      "abbreviation_STD": "PST",
                      "abbreviation_DST": "PDT"
                    },
                    "plus_code": "849VGP3P+3C",
                    "plus_code_short": "3P+3C, 94070 San Carlos, United States",
                    "rank": {
                      "popularity": 4.377368426402045
                    },
                    "place_id": "5191d442c9e4905ec059cd76853e58c04240c00203e203476f70656e6164647265737365733a616464726573733a75732f63612f73616e5f6d6174656f2d6164647265737365732d636f756e74793a61633138623835353436356330343166"
                  },
                  {
                    "query": {
                      "lon": -122.263801,
                      "lat": 37.502683,
                      "plus_code": "849VGP3P+3F"
                    },
                    "country_code": "us",
                    "housenumber": "656",
                    "street": "Cedar Street",
                    "country": "United States",
                    "county": "San Mateo County",
                    "datasource": {
                      "sourcename": "openaddresses",
                      "attribution": "© OpenAddresses contributors",
                      "license": "BSD-3-Clause License"
                    },
                    "postcode": "94070",
                    "state": "California",
                    "city": "San Carlos",
                    "state_code": "CA",
                    "lon": -122.263964,
                    "lat": 37.502693,
                    "distance": 14.421782254517026,
                    "result_type": "building",
                    "formatted": "656 Cedar Street, San Carlos, CA 94070, United States of America",
                    "address_line1": "656 Cedar Street",
                    "address_line2": "San Carlos, CA 94070, United States of America",
                    "timezone": {
                      "name": "America/Los_Angeles",
                      "offset_STD": "-08:00",
                      "offset_STD_seconds": -28800,
                      "offset_DST": "-07:00",
                      "offset_DST_seconds": -25200,
                      "abbreviation_STD": "PST",
                      "abbreviation_DST": "PDT"
                    },
                    "plus_code": "849VGP3P+3C",
                    "plus_code_short": "3P+3C, 94070 San Carlos, United States",
                    "rank": {
                      "popularity": 4.377368426402045
                    },
                    "place_id": "5191d442c9e4905ec059cd76853e58c04240c00203e203476f70656e6164647265737365733a616464726573733a75732f63612f73616e5f6d6174656f2d6164647265737365732d636f756e74793a61633138623835353436356330343166"
                  }
                ]
            text/csv:
              schema:
                type: string
                description: CSV format with headers and comma-separated values
              example: |
                "query.lon","query.lat","query.plus_code","country_code","housenumber","street","country","county","datasource.sourcename","datasource.attribution","datasource.license","postcode","state","city","state_code","lon","lat","distance","result_type","formatted","address_line1","address_line2","timezone.name","timezone.offset_STD","timezone.offset_STD_seconds","timezone.offset_DST","timezone.offset_DST_seconds","timezone.abbreviation_STD","timezone.abbreviation_DST","plus_code","plus_code_short","rank.popularity","place_id"
                "-122.263801","37.502683","849VGP3P+3F","us","656","Cedar Street","United States","San Mateo County","openaddresses","© OpenAddresses contributors","BSD-3-Clause License","94070","California","San Carlos","CA","-122.263964","37.502693","14.421782254517026","building","656 Cedar Street, San Carlos, CA 94070, United States of America","656 Cedar Street","San Carlos, CA 94070, United States of America","America/Los_Angeles","-08:00","-28800","-07:00","-25200","PST","PDT","849VGP3P+3C","3P+3C, 94070 San Carlos, United States","4.377368426402045","5191d442c9e4905ec059cd76853e58c04240c00203e203476f70656e6164647265737365733a616464726573733a75732f63612f73616e5f6d6174656f2d6164647265737365732d636f756e74793a61633138623835353436356330343166"
                "-122.263801","37.502683","849VGP3P+3F","us","656","Cedar Street","United States","San Mateo County","openaddresses","© OpenAddresses contributors","BSD-3-Clause License","94070","California","San Carlos","CA","-122.263964","37.502693","14.421782254517026","building","656 Cedar Street, San Carlos, CA 94070, United States of America","656 Cedar Street","San Carlos, CA 94070, United States of America","America/Los_Angeles","-08:00","-28800","-07:00","-25200","PST","PDT","849VGP3P+3C","3P+3C, 94070 San Carlos, United States","4.377368426402045","5191d442c9e4905ec059cd76853e58c04240c00203e203476f70656e6164647265737365733a616464726573733a75732f63612f73616e5f6d6174656f2d6164647265737365732d636f756e74793a61633138623835353436356330343166"
        '202':
          description: The job is still processing.
        '400':
          description: Bad Request. The input provided is invalid or improperly formatted. Please verify and correct your request parameters.
        '401':
          description: Unauthorized. The API key is missing, incorrect, or invalid. Please provide a valid API key to authenticate the request.
        '429':
          description: Request limit exceeded. Too many requests have been sent in a short period, surpassing the allowed rate limits.
        '500':
          description: Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. Please try again later or [contact support](mailto:info@geoapify.com) if the issue persists.
components:
  schemas:
    # Batch Job Response (for both forward and reverse)
    BatchJobResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique job identifier
        status:
          type: string
          enum: [pending, processing, completed, failed]
          description: Current job status
        url:
          type: string
          format: uri
          description: URL to retrieve job results
      required:
        - id
        - status
        - url
    
    # Forward Batch Geocoding Results
    BatchForwardGeocodingResults:
      type: array
      items:
        $ref: '#/components/schemas/BatchForwardGeocodingResult'
    
    # Individual forward batch geocoding result (based on documentation example)
    BatchForwardGeocodingResult:
      allOf:
        - $ref: '../common/shared-components.yaml#/components/schemas/LatLonCoordinates'
        - $ref: '../common/shared-components.yaml#/components/schemas/AddressComponents'
        - $ref: '../common/shared-components.yaml#/components/schemas/FormattedAddressFields'
        - type: object
          properties:
            query:
              $ref: '#/components/schemas/BatchForwardQuery'
            datasource:
              $ref: '../common/shared-components.yaml#/components/schemas/Datasource'
            address_line2:
              type: string
              description: The second part of the display address
            state_code:
              type: string
              description: State shortcode
            result_type:
              $ref: '../common/shared-components.yaml#/components/schemas/ResultType'
            rank:
              $ref: '../common/shared-components.yaml#/components/schemas/Rank'
            place_id:
              type: string
              description: Unique identifier for the place
            category:
              type: string
              description: A place category
            name:
              type: string
              description: Location name
            distance:
              type: number
              description: Distance in meters
            timezone:
              $ref: '../common/shared-components.yaml#/components/schemas/Timezone'
            plus_code:
              type: string
              description: Plus code (Open Location Code)
            plus_code_short:
              type: string
              description: Shortened plus code
            bbox:
              $ref: '../common/shared-components.yaml#/components/schemas/BoundingBox'
    
    # Reverse Batch Geocoding Results
    BatchReverseGeocodingResults:
      type: array
      items:
        $ref: '#/components/schemas/BatchReverseGeocodingResult'
    
    # Individual reverse batch geocoding result (based on documentation example)
    BatchReverseGeocodingResult:
      type: object
      properties:
        query:
          $ref: '#/components/schemas/BatchReverseQuery'
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code
        housenumber:
          type: string
          description: House number component of an address
        street:
          type: string
          description: Street component of the address
        country:
          type: string
          description: Country component of the address
        county:
          type: string
          description: County component of the address
        datasource:
          $ref: '../common/shared-components.yaml#/components/schemas/Datasource'
        postcode:
          type: string
          description: Postcode or ZIP code of the address
        state:
          type: string
          description: State component of the address
        city:
          type: string
          description: City component of the address
        state_code:
          type: string
          description: State shortcode
        lon:
          type: number
          format: double
          description: Longitude coordinate of the location
        lat:
          type: number
          format: double
          description: Latitude coordinate of the location
        distance:
          type: number
          description: Distance in meters to the given coordinates
        result_type:
          type: string
          description: Found location type
        formatted:
          type: string
          description: Display address
        address_line1:
          type: string
          description: Main part of the display address
        address_line2:
          type: string
          description: The second part of the display address
        timezone:
          $ref: '../common/shared-components.yaml#/components/schemas/Timezone'
        plus_code:
          type: string
          description: Plus code (Open Location Code)
        plus_code_short:
          type: string
          description: Shortened plus code
        rank:
          $ref: '../common/shared-components.yaml#/components/schemas/Rank'
        place_id:
          type: string
          description: Unique identifier for the place
        name:
          type: string
          description: Location name
        category:
          type: string
          description: A place category
        district:
          type: string
          description: District component of the address
        suburb:
          type: string
          description: Suburb component of the address
    
    # Forward Query Information
    BatchForwardQuery:
      type: object
      properties:
        text:
          type: string
          description: Original query text
        parsed:
          type: object
          description: Parsed query components
          properties:
            housenumber:
              type: string
            street:
              type: string
            postcode:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              type: string
            expected_type:
              type: string
    
    # Reverse Query Information
    BatchReverseQuery:
      type: object
      properties:
        lon:
          type: number
          description: Query longitude
        lat:
          type: number
          description: Query latitude
        plus_code:
          type: string
          description: Plus code for the query coordinates
    
    
    
    
