Google Maps Platform Geolocation API

openapi: 3.2.0
info:
  title: Google Maps Platform Geolocation API
  description: API Specification for Google Maps Platform
  version: 1.22.3
servers:
- url: https://www.googleapis.com
security:
- ApiKeyAuth: []
tags:
- name: Geolocation API
paths:
  /geolocation/v1/geolocate:
    post:
      operationId: geolocate
      servers:
      - url: https://www.googleapis.com
      tags:
      - Geolocation API
      description: 'Geolocation API returns a location and accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect. This document describes the protocol used to send this data to the server and to return a response to the client.


        Communication is done over HTTPS using POST. Both request and response are formatted as JSON, and the content type of both is `application/json`.


        You must specify a key in your request, included as the value of a`key` parameter. A `key` is your application''s API key. This key identifies your application for purposes of quota management. Learn how to get a key.'
      requestBody:
        description: The request body must be formatted as JSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeolocationRequest'
            examples:
              WIFI:
                value:
                  considerIp: 'false'
                  wifiAccessPoints:
                  - macAddress: 84:d4:7e:09:a5:f1
                    signalStrength: -43
                    signalToNoiseRatio: 0
                  - macAddress: 44:48:c1:a6:f3:d0
                    signalStrength: -55
                    signalToNoiseRatio: 0
              Cell Towers:
                value:
                  cellTowers:
                  - cellId: 170402199
                    locationAreaCode: 35632
                    mobileCountryCode: 310
                    mobileNetworkCode: 410
                    age: 0
                    signalStrength: -60
                    timingAdvance: 15
              IP Only:
                value:
                  considerIp: 'true'
        required: false
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationResponse'
              examples:
                WIFI:
                  value:
                    location:
                      lat: 37.421925
                      lng: -122.0841293
                    accuracy: 30
                Cell Towers:
                  value:
                    location:
                      lat: 37.7777247
                      lng: -122.4162853
                    accuracy: 1073
                IP Only:
                  value:
                    location:
                      lat: 37.7802545
                      lng: -122.41590829999998
                    accuracy: 926
        '400':
          description: 400 BAD REQUEST
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request:
                  value:
                    error:
                      code: 400
                      message: Invalid value at 'cell_tower' (type.googleapis.com/maps_api.CellTower), "foo"
                      errors:
                      - message: Invalid value at 'cell_tower' (type.googleapis.com/maps_api.CellTower), "foo"
                        reason: invalid
                      status: INVALID_ARGUMENT
                      details:
                      - '@type': type.googleapis.com/google.rpc.BadRequest
                        fieldViolations:
                        - field: cell_tower
                          description: Invalid value at 'cell_tower' (type.googleapis.com/maps_api.CellTower), "foo"
                Invalid Key:
                  value:
                    error:
                      code: 400
                      message: API key not valid. Please pass a valid API key.
                      errors:
                      - message: API key not valid. Please pass a valid API key.
                        domain: global
                        reason: badRequest
                      status: INVALID_ARGUMENT
                      details:
                      - '@type': type.googleapis.com/google.rpc.ErrorInfo
                        reason: API_KEY_INVALID
                        domain: googleapis.com
                        metadata:
                          service: geolocation.googleapis.com
        '404':
          description: 404 NOT FOUND
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid:
                  value:
                    error:
                      code: 404
                      message: Not Found
                      errors:
                      - message: Not Found
                        domain: geolocation
                        reason: notFound
      summary: Geolocate
      x-summary-source: derived
components:
  schemas:
    GeolocationRequest:
      type: object
      title: GeolocationRequest
      description: The request body must be formatted as JSON. The following fields are supported, and all fields are optional.
      properties:
        homeMobileCountryCode:
          type: integer
          description: The cell tower's Mobile Country Code (MCC).
        homeMobileNetworkCode:
          type: integer
          description: The cell tower's Mobile Network Code. This is the MNC for GSM and WCDMA; CDMA uses the System ID (SID).
        radioType:
          type: string
          description: The mobile radio type. Supported values are lte, gsm, cdma, and wcdma. While this field is optional, it should be included if a value is available, for more accurate results.
        carrier:
          type: string
          description: The carrier name.
        considerIp:
          type: string
          description: Specifies whether to fall back to IP geolocation if wifi and cell tower signals are not available. Defaults to true. Set considerIp to false to disable fall back.
        cellTowers:
          type: array
          description: The request body's cellTowers array contains zero or more cell tower objects.
          items:
            $ref: '#/components/schemas/CellTower'
        wifiAccessPoints:
          type: array
          description: An array of two or more WiFi access point objects.
          items:
            $ref: '#/components/schemas/WiFiAccessPoint'
    WiFiAccessPoint:
      type: object
      title: WiFiAccessPoint
      description: Attributes used to describe a WiFi access point.
      required:
      - macAddress
      properties:
        macAddress:
          description: The MAC address of the WiFi node. It's typically called a BSS, BSSID or MAC address. Separators must be `:` (colon).
          type: string
        signalStrength:
          description: The current signal strength measured in dBm.
          type: integer
        signalToNoiseRatio:
          description: The current signal to noise ratio measured in dB.
          type: integer
        age:
          description: The number of milliseconds since this access point was detected.
          type: integer
        channel:
          description: The channel over which the client is communication with the access point.
          type: integer
      example:
        considerIp: 'false'
        wifiAccessPoints:
        - macAddress: 84:d4:7e:09:a5:f1
          signalStrength: -43
          signalToNoiseRatio: 0
        - macAddress: 44:48:c1:a6:f3:d0
          signalStrength: -55
          signalToNoiseRatio: 0
    ErrorObject:
      type: object
      title: ErrorObject
      required:
      - code
      - message
      - errors
      properties:
        code:
          description: This is the same as the HTTP status of the response.
          type: number
        message:
          description: A short description of the error.
          type: string
        errors:
          description: A list of errors which occurred. Each error contains an identifier for the type of error and a short description.
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        status:
          description: A status code that indicates the error type.
          type: string
        details:
          description: Additional details about the error.
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorResponse:
      type: object
      title: ErrorResponse
      description: In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
      required:
      - error
      properties:
        error:
          description: An error return by the server.
          $ref: '#/components/schemas/ErrorObject'
      example:
        error:
          code: 400
          message: API key not valid. Please pass a valid API key.
          errors:
          - message: API key not valid. Please pass a valid API key.
            domain: global
            reason: badRequest
          status: INVALID_ARGUMENT
          details:
          - '@type': type.googleapis.com/google.rpc.ErrorInfo
            reason: API_KEY_INVALID
            domain: googleapis.com
            metadata:
              service: geolocation.googleapis.com
    CellTower:
      type: object
      title: CellTower
      description: 'Attributes used to describe a cell tower. The following optional fields are not currently used, but may be included if values are available: `age`, `signalStrength`, `timingAdvance`.'
      required:
      - cellId
      - locationAreaCode
      - mobileCountryCode
      - mobileNetworkCode
      properties:
        cellId:
          description: Unique identifier of the cell. On GSM, this is the Cell ID (CID); CDMA networks use the Base Station ID (BID). WCDMA networks use the UTRAN/GERAN Cell Identity (UC-Id), which is a 32-bit value concatenating the Radio Network Controller (RNC) and Cell ID. Specifying only the 16-bit Cell ID value in WCDMA networks may return inaccurate results.
          type: integer
        locationAreaCode:
          description: The Location Area Code (LAC) for GSM and WCDMA networks. The Network ID (NID) for CDMA networks.
          type: integer
        mobileCountryCode:
          description: The cell tower's Mobile Country Code (MCC).
          type: integer
        mobileNetworkCode:
          description: The cell tower's Mobile Network Code. This is the MNC for GSM and WCDMA; CDMA uses the System ID (SID).
          type: integer
        age:
          description: The number of milliseconds since this cell was primary. If age is 0, the cellId represents a current measurement.
          type: integer
        signalStrength:
          description: Radio signal strength measured in dBm.
          type: number
        timingAdvance:
          description: The timing advance value.
          type: number
      example:
        cellTowers:
        - cellId: 170402199
          locationAreaCode: 35632
          mobileCountryCode: 310
          mobileNetworkCode: 410
          age: 0
          signalStrength: -60
          timingAdvance: 15
    FieldViolation:
      type: object
      title: FieldViolation
      required:
      - field
      - description
      properties:
        field:
          description: The name of the invalid field.
          type: string
        description:
          description: A short description of the error.
          type: string
    GeolocationResponse:
      type: object
      title: GeolocationResponse
      description: A successful geolocation request will return a JSON-formatted response defining a location and radius.
      required:
      - location
      - accuracy
      properties:
        location:
          description: The user’s estimated latitude and longitude, in degrees.
          $ref: '#/components/schemas/LatLngLiteral'
        accuracy:
          description: The accuracy of the estimated location, in meters. This represents the radius of a circle around the given `location`. If your Geolocation response shows a very high value in the `accuracy` field, the service may be geolocating based on the  request IP, instead of WiFi points or cell towers. This can happen if no cell towers or access points are valid or recognized. To confirm that this is the issue, set `considerIp` to `false` in your request. If the response is a `404`, you've confirmed that your `wifiAccessPoints` and `cellTowers` objects could not be geolocated.
          type: number
      example:
        location:
          lat: 37.421925
          lng: -122.0841293
        accuracy: 30
    ErrorDetail:
      type: object
      title: ErrorDetail
      properties:
        '@type':
          description: The type of error.
          type: string
          example: type.googleapis.com/google.rpc.ErrorInfo
        message:
          description: A short description of the error.
          type: string
        reason:
          type: string
          description: A reason for the error.
        domain:
          type: string
          description: The domain in which the error occurred.
        metadata:
          type: object
          description: Additional metadata about the error.
        fieldViolations:
          description: A list of field violations.
          type: array
          items:
            $ref: '#/components/schemas/FieldViolation'
      example:
        message: API key not valid. Please pass a valid API key.
        domain: global
        reason: badRequest
    LatLngLiteral:
      type: object
      title: LatLngLiteral
      description: An object describing a specific location with Latitude and Longitude in decimal degrees.
      required:
      - lat
      - lng
      properties:
        lat:
          type: number
          description: Latitude in decimal degrees
        lng:
          type: number
          description: Longitude in decimal degrees
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key