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

# Geocode an Address

> Geocode a free-text address into ranked, un-persisted candidates.

export const permission_0 = 'element:read'

<Info>Requires permission: **{permission_0}**</Info>


## OpenAPI

````yaml GET /v1/geolocation
openapi: 3.0.1
info:
  title: Variable API
  description: This is the Variable API
  version: 1.1.0
servers:
  - url: https://app.variable.global/api
security:
  - basicAuth: []
  - bearerAuth: []
  - oAuthNoScopes: []
paths:
  /v1/geolocation:
    get:
      summary: Geocode an address into candidate locations
      description: >
        Geocode a free-text address (e.g. `Syracuse, NY`) into ranked,
        **un-persisted**

        candidates. Each candidate carries a `googleMapsId`, `name`,
        `countryCode`, and

        coordinates but no `uuid` — resolve any ambiguity here, then persist a
        chosen

        candidate with `POST /v1/geolocation` (or reference its `googleMapsId`
        directly

        on a transport leg).
      parameters:
        - name: search
          in: query
          description: Free-text address or place to geocode (max 200 characters)
          required: true
          schema:
            type: string
            maxLength: 200
          example: Syracuse, NY
      responses:
        '200':
          description: Ranked, un-persisted geolocation candidates
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    example: 3
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiGeoLocation'
        '401':
          description: ExpiredToken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpiredTokenResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ApiGeoLocation:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: >-
            Present only on a persisted geolocation (the POST response); absent
            on search candidates.
        googleMapsId:
          type: string
          example: ChIJA4UGSG_xNIgRNBuiWqEV-Y0
        name:
          type: string
          description: The geocoder's formatted address.
          example: Syracuse, NY, USA
        countryCode:
          type: string
          example: US
        latitude:
          type: number
          example: 43.0481
        longitude:
          type: number
          example: -76.1474
        locationType:
          type: string
          example: APPROXIMATE
    ExpiredTokenResponse:
      type: object
      properties:
        message:
          type: string
          example: token expired
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oAuthNoScopes:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes: {}

````