> ## 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.

# Lookup

> Retrieves a full address by its GeoScale identifier.



## OpenAPI

````yaml GET /address/{id}
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/{id}:
    get:
      summary: Lookup address
      description: Retrieves a full address by its GeoScale identifier.
      operationId: getAddress
      parameters:
        - name: id
          in: path
          required: true
          description: Stable GeoScale address identifier.
          schema:
            type: string
        - name: lang
          in: query
          required: false
          description: BCP 47 language tag used for localization of the response.
          schema:
            type: string
      responses:
        '200':
          description: Address returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
              examples:
                netherlands:
                  $ref: '#/components/examples/LookupResponseNL'
                belgium:
                  $ref: '#/components/examples/LookupResponseBE'
                luxembourg:
                  $ref: '#/components/examples/LookupResponseLU'
                france:
                  $ref: '#/components/examples/LookupResponseFR'
        '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'
        '404':
          description: Address not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                addressNotFound:
                  $ref: '#/components/examples/ErrorAddressNotFound'
        '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:
    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'
    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.
    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:
    LookupResponseNL:
      summary: Lookup response with a Dutch street address
      description: Example response for looking up a Dutch address by ID.
      value:
        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
    LookupResponseBE:
      summary: Lookup response with a Belgian street address
      description: Example response for looking up a Belgian address by ID.
      value:
        id: jp1p2kJ6PX2cPVBP
        type: be_street_address
        street: Rue de la Loi
        house_number: '16'
        postal_code: '1000'
        municipality: Bruxelles
        arrondissement: Arrondissement de Bruxelles-Capitale
        region: Région de Bruxelles-Capitale
        country: Belgique
        location:
          latitude: 50.846162
          longitude: 4.366528
        single_line: Rue de la Loi 16, 1000 Bruxelles
        lines:
          - Rue de la Loi 16
          - 1000 Bruxelles
          - Belgique
    LookupResponseLU:
      summary: Lookup response with a Luxembourg street address
      description: Example response for looking up a Luxembourg address by ID.
      value:
        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
    LookupResponseFR:
      summary: Lookup response with a French street address
      description: Example response for looking up a French address by ID.
      value:
        id: 1JzjIgaZG4qjdhiL88Mn3STsQB
        type: fr_street_address
        house_number: '55'
        street: Rue du Faubourg Saint-Honoré
        postal_code: '75008'
        commune: Paris
        country: France
        location:
          latitude: 48.87063
          longitude: 2.316931
        single_line: 55 Rue du Faubourg Saint-Honoré, 75008 Paris
        lines:
          - 55 Rue du Faubourg Saint-Honoré
          - 75008 Paris
          - France
    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
    ErrorAddressNotFound:
      summary: Address not found
      description: >-
        The provided GeoScale address identifier does not correspond to an
        existing address.
      value:
        title: Not Found
        status: 404
        detail: Address not found
        instance: /v1/address/lrpI42Dp0YB
    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

````