> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geoscale.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Autocomplete

> Returns address suggestions for a partial address query.



## OpenAPI

````yaml GET /address
openapi: 3.1.1
info:
  title: GeoScale Address API
  description: >
    GeoScale Address API is an address autocomplete API designed for
    high-quality, country-specific

    address search.
  version: 1.0.0
servers:
  - url: https://api.geoscale.io/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /address:
    get:
      summary: Autocomplete addresses
      description: Returns address suggestions for a partial address query.
      operationId: autocompleteAddresses
      parameters:
        - name: country
          in: query
          required: true
          description: Two-letter country code (ISO 3166-1 alpha-2).
          schema:
            type: string
            enum:
              - BE
              - FR
              - LU
              - NL
        - name: q
          in: query
          required: true
          description: Partial address input. Must contain at least one character.
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: lang
          in: query
          required: false
          description: >
            BCP 47 language tag used for localization of the response. Does not
            affect search

            matching or ranking.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: >
            Maximum number of suggestions to return.


            **Note:** Results are ranked for the requested limit.

            Requesting a higher limit and then truncating the result list
            client-side may lead to

            suboptimal ranking of the remaining results.
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 5
      responses:
        '200':
          description: Autocomplete suggestions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
              examples:
                belgium:
                  $ref: '#/components/examples/AutocompleteResponseBE'
                luxembourg:
                  $ref: '#/components/examples/AutocompleteResponseLU'
                netherlands:
                  $ref: '#/components/examples/AutocompleteResponseNL'
                france:
                  $ref: '#/components/examples/AutocompleteResponseFR'
                empty:
                  $ref: '#/components/examples/AutocompleteEmptyResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                missingCountry:
                  $ref: '#/components/examples/ErrorMissingCountry'
                unsupportedCountry:
                  $ref: '#/components/examples/ErrorUnsupportedCountry'
                missingQuery:
                  $ref: '#/components/examples/ErrorMissingQuery'
                queryTooShort:
                  $ref: '#/components/examples/ErrorQueryTooShort'
                queryTooLong:
                  $ref: '#/components/examples/ErrorQueryTooLong'
                limitTooLow:
                  $ref: '#/components/examples/ErrorLimitTooLow'
                limitTooHigh:
                  $ref: '#/components/examples/ErrorLimitTooHigh'
        '401':
          description: Authentication failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                missingApiKey:
                  $ref: '#/components/examples/ErrorMissingApiKey'
                invalidApiKey:
                  $ref: '#/components/examples/ErrorInvalidApiKey'
        '402':
          description: The API key is valid but no active subscription exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                noActiveSubscription:
                  $ref: '#/components/examples/ErrorNoActiveSubscription'
        '429':
          description: Too many requests.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                rateLimitExceeded:
                  $ref: '#/components/examples/ErrorRateLimitExceeded'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                internalError:
                  $ref: '#/components/examples/ErrorInternalServer'
components:
  schemas:
    AutocompleteResponse:
      type: object
      description: Address autocomplete result set.
      required:
        - hits
      properties:
        hits:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Address'
    ProblemDetails:
      type: object
      description: |
        Error response following RFC 7807 (Problem Details for HTTP APIs).
      required:
        - title
        - status
        - detail
        - instance
      properties:
        type:
          type: string
          description: URI reference identifying the problem type.
        title:
          type: string
          description: Short, human-readable summary.
        status:
          type: integer
          description: HTTP status code.
        detail:
          type: string
          description: Human-readable explanation.
        instance:
          type: string
          description: URI of the request that caused the error.
    Address:
      oneOf:
        - $ref: '#/components/schemas/BeStreetAddress'
        - $ref: '#/components/schemas/FrStreetAddress'
        - $ref: '#/components/schemas/LuStreetAddress'
        - $ref: '#/components/schemas/NlStreetAddress'
      discriminator:
        propertyName: type
        mapping:
          be_street_address:
            $ref: '#/components/schemas/BeStreetAddress'
          fr_street_address:
            $ref: '#/components/schemas/FrStreetAddress'
          lu_street_address:
            $ref: '#/components/schemas/LuStreetAddress'
          nl_street_address:
            $ref: '#/components/schemas/NlStreetAddress'
    BeStreetAddress:
      title: Belgian street address
      allOf:
        - $ref: '#/components/schemas/AddressBase'
        - type: object
          description: Structured Belgian street address.
          required:
            - type
            - street
            - house_number
            - postal_code
            - municipality
            - arrondissement
            - region
            - country
          properties:
            type:
              const: be_street_address
            street:
              type: string
            house_number:
              type: string
            box_number:
              type: string
            postal_code:
              type: string
            municipality:
              type: string
            arrondissement:
              type: string
            province:
              type: string
            region:
              type: string
            country:
              type: string
    FrStreetAddress:
      title: French street address
      allOf:
        - $ref: '#/components/schemas/AddressBase'
        - type: object
          description: Structured French street address.
          required:
            - type
            - street
            - house_number
            - postal_code
            - commune
            - country
          properties:
            type:
              const: fr_street_address
            house_number:
              type: string
            repetition_index:
              type: string
            street:
              type: string
            postal_code:
              type: string
            commune:
              type: string
            country:
              type: string
    LuStreetAddress:
      title: Luxembourg street address
      allOf:
        - $ref: '#/components/schemas/AddressBase'
        - type: object
          description: Structured Luxembourg street address.
          required:
            - type
            - street
            - house_number
            - postal_code
            - locality
            - commune
            - canton
            - country
          properties:
            type:
              const: lu_street_address
            street:
              type: string
            house_number:
              type: string
            multiple_code:
              type: string
            postal_code:
              type: string
            locality:
              type: string
            commune:
              type: string
            canton:
              type: string
            country:
              type: string
    NlStreetAddress:
      title: Dutch street address
      allOf:
        - $ref: '#/components/schemas/AddressBase'
        - type: object
          description: Structured Dutch street address.
          required:
            - type
            - street
            - house_number
            - postal_code
            - locality
            - municipality
            - province
            - country
          properties:
            type:
              const: nl_street_address
            street:
              type: string
            house_number:
              type: string
            house_letter:
              type: string
            house_number_addition:
              type: string
            postal_code:
              type: string
            locality:
              type: string
            municipality:
              type: string
            province:
              type: string
            country:
              type: string
    AddressBase:
      type: object
      description: Shared fields present on every address result.
      required:
        - id
        - type
        - single_line
        - lines
      properties:
        id:
          type: string
          description: Stable GeoScale address identifier.
        type:
          type: string
          description: Address subtype discriminator.
        location:
          $ref: '#/components/schemas/Location'
        single_line:
          type: string
          description: Compact, single-line address formatted for display.
        lines:
          type: array
          description: >-
            Multi-line, locale-correct formatted address suitable for display or
            printing.
          items:
            type: string
    Location:
      type: object
      description: Geographic coordinates in WGS84.
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
  examples:
    AutocompleteResponseBE:
      summary: Autocomplete response with Belgian street addresses
      description: Example response for the query `rue de la loi 16` in Belgium.
      value:
        hits:
          - id: jp1p2kJ5yXvAwnMp
            type: be_street_address
            street: Rue de la Loi
            house_number: '16'
            postal_code: '7170'
            municipality: Manage
            arrondissement: Arrondissement de Soignies
            province: Province du Hainaut
            region: Région wallonne
            country: Belgique
            location:
              latitude: 50.475721
              longitude: 4.236087
            single_line: Rue de la Loi 16, 7170 Manage
            lines:
              - Rue de la Loi 16
              - 7170 Manage
              - Belgique
          - id: 1i7jNnDAaTevq7abmi
            type: be_street_address
            street: Rue de la Loi
            house_number: '16'
            box_number: '0002'
            postal_code: '4020'
            municipality: Liège
            arrondissement: Arrondissement de Liège
            province: Province de Liège
            region: Région wallonne
            country: Belgique
            location:
              latitude: 50.642752
              longitude: 5.585497
            single_line: Rue de la Loi 16 0002, 4020 Liège
            lines:
              - Rue de la Loi 16 0002
              - 4020 Liège
              - Belgique
          - id: jp1p2kJ5zAnjBzoJ
            type: be_street_address
            street: Rue de la Loi
            house_number: '16'
            postal_code: '7100'
            municipality: La Louvière
            arrondissement: Arrondissement de La Louvière
            province: Province du Hainaut
            region: Région wallonne
            country: Belgique
            location:
              latitude: 50.478136
              longitude: 4.186106
            single_line: Rue de la Loi 16, 7100 La Louvière
            lines:
              - Rue de la Loi 16
              - 7100 La Louvière
              - Belgique
          - id: jp1p2kJ5yXvAwnMo
            type: be_street_address
            street: Rue de la Loi
            house_number: '160'
            postal_code: '7170'
            municipality: Manage
            arrondissement: Arrondissement de Soignies
            province: Province du Hainaut
            region: Région wallonne
            country: Belgique
            location:
              latitude: 50.476678
              longitude: 4.231801
            single_line: Rue de la Loi 160, 7170 Manage
            lines:
              - Rue de la Loi 160
              - 7170 Manage
              - Belgique
          - id: jp1p2kJ5yXvAwnMn
            type: be_street_address
            street: Rue de la Loi
            house_number: '164'
            postal_code: '7170'
            municipality: Manage
            arrondissement: Arrondissement de Soignies
            province: Province du Hainaut
            region: Région wallonne
            country: Belgique
            location:
              latitude: 50.476666
              longitude: 4.231588
            single_line: Rue de la Loi 164, 7170 Manage
            lines:
              - Rue de la Loi 164
              - 7170 Manage
              - Belgique
    AutocompleteResponseLU:
      summary: Autocomplete response with Luxembourg street addresses
      description: Example response for the query `rue du marché 1` in Luxembourg.
      value:
        hits:
          - id: 55vvgW04revtH22
            type: lu_street_address
            house_number: '1'
            street: Rue du Marché-aux-Herbes
            postal_code: '1728'
            locality: Luxembourg
            commune: Luxembourg
            canton: Luxembourg
            country: Luxembourg
            location:
              latitude: 49.611797
              longitude: 6.132318
            single_line: 1, Rue du Marché-aux-Herbes, Luxembourg
            lines:
              - 1, Rue du Marché-aux-Herbes
              - L-1728 Luxembourg
              - Luxembourg
          - id: 55vvgW04revtH69
            type: lu_street_address
            house_number: '2'
            street: Rue du Marché-aux-Herbes
            postal_code: '1728'
            locality: Luxembourg
            commune: Luxembourg
            canton: Luxembourg
            country: Luxembourg
            location:
              latitude: 49.611695
              longitude: 6.132191
            single_line: 2, Rue du Marché-aux-Herbes, Luxembourg
            lines:
              - 2, Rue du Marché-aux-Herbes
              - L-1728 Luxembourg
              - Luxembourg
          - id: 55vvgW04revtH6a
            type: lu_street_address
            house_number: '4'
            street: Rue du Marché-aux-Herbes
            postal_code: '1728'
            locality: Luxembourg
            commune: Luxembourg
            canton: Luxembourg
            country: Luxembourg
            location:
              latitude: 49.611623
              longitude: 6.132205
            single_line: 4, Rue du Marché-aux-Herbes, Luxembourg
            lines:
              - 4, Rue du Marché-aux-Herbes
              - L-1728 Luxembourg
              - Luxembourg
          - id: 55vvgW04revtH24
            type: lu_street_address
            house_number: '5'
            street: Rue du Marché-aux-Herbes
            postal_code: '1728'
            locality: Luxembourg
            commune: Luxembourg
            canton: Luxembourg
            country: Luxembourg
            location:
              latitude: 49.611698
              longitude: 6.132405
            single_line: 5, Rue du Marché-aux-Herbes, Luxembourg
            lines:
              - 5, Rue du Marché-aux-Herbes
              - L-1728 Luxembourg
              - Luxembourg
          - id: 55vvgW04revtH6b
            type: lu_street_address
            house_number: '6'
            street: Rue du Marché-aux-Herbes
            postal_code: '1728'
            locality: Luxembourg
            commune: Luxembourg
            canton: Luxembourg
            country: Luxembourg
            location:
              latitude: 49.611324
              longitude: 6.132256
            single_line: 6, Rue du Marché-aux-Herbes, Luxembourg
            lines:
              - 6, Rue du Marché-aux-Herbes
              - L-1728 Luxembourg
              - Luxembourg
    AutocompleteResponseNL:
      summary: Autocomplete response with 5 Dutch street addresses
      description: Example response for the query `dam 1` in the Netherlands.
      value:
        hits:
          - id: 25p8hdho2ucpbSc6g1QSythIGj3dzN
            type: nl_street_address
            street: Dam
            house_number: '1'
            postal_code: 1012 JS
            locality: Amsterdam
            municipality: Amsterdam
            province: Noord-Holland
            country: Nederland
            location:
              latitude: 52.373293
              longitude: 4.893718
            single_line: Dam 1, Amsterdam
            lines:
              - Dam 1
              - 1012 JS Amsterdam
              - Nederland
          - id: 25p8hdho2ucRDBOUd62TKCOYqRjdXW
            type: nl_street_address
            street: Dam
            house_number: '1'
            postal_code: 1506 BC
            locality: Zaandam
            municipality: Zaanstad
            province: Noord-Holland
            country: Nederland
            location:
              latitude: 52.439496
              longitude: 4.825241
            single_line: Dam 1, Zaandam
            lines:
              - Dam 1
              - 1506 BC Zaandam
              - Nederland
          - id: 25p8hdho2udLwV3DSfw84vE3hUvVtw
            type: nl_street_address
            street: Dam
            house_number: '1'
            postal_code: 3111 BC
            locality: Schiedam
            municipality: Schiedam
            province: Zuid-Holland
            country: Nederland
            location:
              latitude: 51.917776
              longitude: 4.395723
            single_line: Dam 1, Schiedam
            lines:
              - Dam 1
              - 3111 BC Schiedam
              - Nederland
          - id: 25p8hdho2ucRKhDLQ09DIfnReDaY0B
            type: nl_street_address
            street: Dam
            house_number: '1'
            postal_code: 2952 AB
            locality: Alblasserdam
            municipality: Alblasserdam
            province: Zuid-Holland
            country: Nederland
            location:
              latitude: 51.858704
              longitude: 4.660075
            single_line: Dam 1, Alblasserdam
            lines:
              - Dam 1
              - 2952 AB Alblasserdam
              - Nederland
          - id: 25p8hdho2udMc2spToi8mB7a3obaKu
            type: nl_street_address
            street: Dam
            house_number: '1'
            postal_code: 4461 HV
            locality: Goes
            municipality: Goes
            province: Zeeland
            country: Nederland
            location:
              latitude: 51.501864
              longitude: 3.890381
            single_line: Dam 1, Goes
            lines:
              - Dam 1
              - 4461 HV Goes
              - Nederland
    AutocompleteResponseFR:
      summary: Autocomplete response with 5 French street addresses
      description: Example response for the query `55 rue du faubourg` in France.
      value:
        hits:
          - id: 1JzjIcqQbP8pCvOTEwGqvgKyuV
            type: fr_street_address
            house_number: '55'
            street: Rue du Faubourg de Lille
            postal_code: '59870'
            commune: Marchiennes
            country: France
            location:
              latitude: 50.408625
              longitude: 3.276433
            single_line: 55 Rue du Faubourg de Lille, 59870 Marchiennes
            lines:
              - 55 Rue du Faubourg de Lille
              - 59870 Marchiennes
              - France
          - id: 1JzjI4PFwYV4lZ1xDEKHQi0g2p
            type: fr_street_address
            house_number: '55'
            street: Rue du Faubourg
            postal_code: '12300'
            commune: Livinhac-le-Haut
            country: France
            location:
              latitude: 44.589479
              longitude: 2.230859
            single_line: 55 Rue du Faubourg, 12300 Livinhac-le-Haut
            lines:
              - 55 Rue du Faubourg
              - 12300 Livinhac-le-Haut
              - France
          - id: 1JzjIg9aMNHXtRsZNGU9ry2jkx
            type: fr_street_address
            house_number: '55'
            street: Rue du Faubourg
            postal_code: '71130'
            commune: Uxeau
            country: France
            location:
              latitude: 46.661872
              longitude: 4.024282
            single_line: 55 Rue du Faubourg, 71130 Uxeau
            lines:
              - 55 Rue du Faubourg
              - 71130 Uxeau
              - France
          - id: 1JzjIawtygqkjQV2V6uOYjQMst
            type: fr_street_address
            house_number: '55'
            street: Rue du Faubourg de l’Ollier
            postal_code: '46400'
            commune: Saint-Céré
            country: France
            location:
              latitude: 44.861887
              longitude: 1.89121
            single_line: 55 Rue du Faubourg de l’Ollier, 46400 Saint-Céré
            lines:
              - 55 Rue du Faubourg de l’Ollier
              - 46400 Saint-Céré
              - France
          - id: 1JzjI2YXG0ZB1sSSqXlf5huDVb
            type: fr_street_address
            house_number: '55'
            street: Rue du Faubourg
            postal_code: '07150'
            commune: Lagorce
            country: France
            location:
              latitude: 44.450177
              longitude: 4.417251
            single_line: 55 Rue du Faubourg, 07150 Lagorce
            lines:
              - 55 Rue du Faubourg
              - 07150 Lagorce
              - France
    AutocompleteEmptyResponse:
      summary: No matching addresses found
      description: >-
        The request was valid, but no address matches were found for the given
        query.
      value:
        hits: []
    ErrorMissingCountry:
      summary: Missing country parameter
      value:
        title: Bad Request
        status: 400
        detail: Required parameter 'country' is not present.
        instance: /v1/address
    ErrorUnsupportedCountry:
      summary: Unsupported country code
      value:
        title: Bad Request
        status: 400
        detail: 'Unsupported country code: DE'
        instance: /v1/address
    ErrorMissingQuery:
      summary: Missing query parameter
      value:
        title: Bad Request
        status: 400
        detail: Required parameter 'q' is not present.
        instance: /v1/address
    ErrorQueryTooShort:
      summary: Query is empty
      description: The query parameter was provided but contains no characters.
      value:
        title: Bad Request
        status: 400
        detail: Query parameter 'q' must not be empty
        instance: /v1/address
    ErrorQueryTooLong:
      summary: Query exceeds maximum length
      value:
        title: Bad Request
        status: 400
        detail: Query parameter 'q' must not exceed 128 characters
        instance: /v1/address
    ErrorLimitTooLow:
      summary: Limit below minimum
      value:
        title: Bad Request
        status: 400
        detail: Query parameter 'limit' must be greater than or equal to 1
        instance: /v1/address
    ErrorLimitTooHigh:
      summary: Limit exceeds maximum
      value:
        title: Bad Request
        status: 400
        detail: Query parameter 'limit' must not exceed 10
        instance: /v1/address
    ErrorMissingApiKey:
      summary: Missing API key
      value:
        title: Unauthorized
        status: 401
        detail: Missing API key
        instance: /v1/address
    ErrorInvalidApiKey:
      summary: Invalid API key
      value:
        title: Unauthorized
        status: 401
        detail: Invalid API key
        instance: /v1/address
    ErrorNoActiveSubscription:
      summary: No active subscription
      value:
        title: Payment required
        status: 402
        detail: No active subscription
        instance: /v1/address
    ErrorRateLimitExceeded:
      summary: Rate limit exceeded
      value:
        title: Too many requests
        status: 429
        detail: Rate limit exceeded
        instance: /v1/address
    ErrorInternalServer:
      summary: Unexpected server error
      value:
        title: Internal Server Error
        status: 500
        detail: An unexpected error occurred.
        instance: /v1/address
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````