openapi: 3.0.1
info:
  title: Geoapify Forward Geocoding Geocode API
  description: Geoapify's Forward Geocoding API for searching addresses worldwide. This API accepts both structured and free-form addresses and returns results in JSON, GeoJSON, or XML formats.
  version: 1.0.0
  contact:
    name: Geoapify Support
    email: info@geoapify.com
    url: https://www.geoapify.com/support
servers:
- url: https://api.geoapify.com/v1
tags:
- name: Geocode
paths:
  /geocode/search:
    get:
      summary: Forward Geocoding
      description: Convert addresses into geographic coordinates using free-form or structured input.
      parameters:
      - name: apiKey
        in: query
        required: true
        schema:
          type: string
        description: Your API key for accessing the Geoapify API.
      - name: text
        in: query
        schema:
          type: string
        description: Free-form address input.
      - name: name
        in: query
        schema:
          type: string
        description: Amenity or place name as part of a structured address.
      - name: housenumber
        in: query
        schema:
          type: string
        description: House number for a structured address.
      - name: street
        in: query
        schema:
          type: string
        description: Street name for a structured address.
      - name: postcode
        in: query
        schema:
          type: string
        description: Postal code or ZIP code.
      - name: city
        in: query
        schema:
          type: string
        description: City name.
      - name: state
        in: query
        schema:
          type: string
        description: State name.
      - name: country
        in: query
        schema:
          type: string
        description: Country name.
      - name: type
        in: query
        schema:
          type: string
          enum:
          - country
          - state
          - city
          - postcode
          - street
          - amenity
          - locality
        description: Location type filter to narrow down search by type.
      - name: lang
        in: query
        schema:
          type: string
        description: Language code for the response (2-character ISO 639-1).
      - name: limit
        in: query
        schema:
          type: integer
          default: 5
        description: Maximum number of results to return.
      - name: filter
        in: query
        schema:
          type: string
        description: Filter results by location constraints (e.g., country, boundary).
      - name: bias
        in: query
        schema:
          type: string
        description: Location bias to prioritize search results by proximity or area.
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - xml
          - geojson
          default: json
        description: Response format.
      responses:
        '200':
          description: Successful response with geocoding results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        datasource:
                          type: object
                          properties:
                            sourcename:
                              type: string
                            attribution:
                              type: string
                            license:
                              type: string
                            url:
                              type: string
                        housenumber:
                          type: string
                        street:
                          type: string
                        suburb:
                          type: string
                        city:
                          type: string
                        county:
                          type: string
                        state:
                          type: string
                        postcode:
                          type: string
                        country:
                          type: string
                        country_code:
                          type: string
                        lon:
                          type: number
                          format: float
                        lat:
                          type: number
                          format: float
                        formatted:
                          type: string
                        address_line1:
                          type: string
                        address_line2:
                          type: string
                        state_code:
                          type: string
                        result_type:
                          type: string
                        rank:
                          type: object
                          properties:
                            importance:
                              type: number
                              format: float
                            popularity:
                              type: number
                              format: float
                            confidence:
                              type: number
                              format: float
                            confidence_city_level:
                              type: number
                              format: float
                            confidence_street_level:
                              type: number
                              format: float
                            match_type:
                              type: string
                        timezone:
                          type: object
                          properties:
                            name:
                              type: string
                            offset_STD:
                              type: string
                            offset_STD_seconds:
                              type: integer
                            offset_DST:
                              type: string
                            offset_DST_seconds:
                              type: integer
                            abbreviation_STD:
                              type: string
                            abbreviation_DST:
                              type: string
                        place_id:
                          type: string
            application/xml:
              schema:
                type: string
                description: XML formatted response.
        '400':
          description: Bad Request, usually due to missing or invalid parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        '401':
          description: Unauthorized, invalid API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Unauthorized error message
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Internal server error message
      tags:
      - Geocode