openapi: 3.1.0
info:
title: Google Maps Directions Autocomplete Geocoding API
description: The Google Maps Directions API returns directions between locations using HTTP requests. Directions may specify origins, destinations, and waypoints as text strings (e.g., an address or place name), place IDs, or latitude/longitude coordinates. The API supports driving, walking, bicycling, and transit travel modes with real-time traffic awareness.
version: '1.0'
termsOfService: https://cloud.google.com/maps-platform/terms
contact:
name: Google Maps Platform Team
url: https://developers.google.com/maps/support
license:
name: Google Maps Platform Terms of Service
url: https://cloud.google.com/maps-platform/terms
x-logo:
url: https://developers.google.com/maps/images/maps-icon.svg
servers:
- url: https://maps.googleapis.com/maps/api
description: Google Maps Directions API production server
security:
- apiKey: []
tags:
- name: Geocoding
description: Forward and reverse geocoding operations
externalDocs:
description: Geocoding API reference
url: https://developers.google.com/maps/documentation/geocoding/requests-geocoding
paths:
/geocode/json:
get:
operationId: geocode
summary: Geocode an Address or Reverse Geocode Coordinates
description: Converts a human-readable address into geographic coordinates (latitude/longitude), or converts coordinates into a human-readable address (reverse geocoding). At least one of the `address`, `components`, or `latlng` parameters is required.
tags:
- Geocoding
parameters:
- name: address
in: query
description: The street address or plus code to geocode. Specify addresses in accordance with the format used by the national postal service of the country concerned. Additional address elements such as business names should not be included.
schema:
type: string
example: 1600 Amphitheatre Parkway, Mountain View, CA
- name: latlng
in: query
description: The latitude and longitude values for reverse geocoding, specified as a comma-separated string (e.g., 40.714224,-73.961452).
schema:
type: string
example: 40.714224,-73.961452
- name: place_id
in: query
description: The place ID of the place for which to obtain the human-readable address. The place ID uniquely identifies a place in the Google Places database and on Google Maps.
schema:
type: string
example: ChIJd8BlQ2BZwokRAFUEcm_qrcA
- name: components
in: query
description: A component filter for which to obtain a geocode, specified as a pipe-separated list of component:value pairs. Components can be used to filter results to a particular country, administrative area, locality, postal code, or route.
schema:
type: string
example: country:US|postal_code:94043
- name: bounds
in: query
description: The bounding box of the viewport within which to bias geocode results more prominently. Specified as pipe-separated southwest and northeast coordinates (lat,lng|lat,lng).
schema:
type: string
example: 34.172684,-118.604794|34.236144,-118.500938
- name: region
in: query
description: The region code, specified as a ccTLD two-character value. This parameter biases results towards a particular region.
schema:
type: string
example: us
- name: language
in: query
description: The language in which to return results. If not supplied, the geocoder attempts to use the preferred language as specified in the Accept-Language header, or the native language of the domain from which the request is sent.
schema:
type: string
example: en
- name: result_type
in: query
description: A pipe-separated list of one or more address types. Used for reverse geocoding to filter results by address type (e.g., street_address, route, intersection, political, country, etc.).
schema:
type: string
example: street_address|route
- name: location_type
in: query
description: A pipe-separated list of one or more location types. Used for reverse geocoding to filter results by location type. Values include ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, and APPROXIMATE.
schema:
type: string
enum:
- ROOFTOP
- RANGE_INTERPOLATED
- GEOMETRIC_CENTER
- APPROXIMATE
example: ROOFTOP
- name: key
in: query
required: true
description: Your application's API key. This key identifies your application for purposes of quota management.
schema:
type: string
example: example_value
responses:
'200':
description: Geocoding response
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodingResponse'
examples:
Geocode200Example:
summary: Default geocode 200 response
x-microcks-default: true
value:
status: OK
results:
- address_components: {}
formatted_address: example_value
place_id: '500123'
types: {}
partial_match: true
error_message: example_value
'400':
description: Bad request - invalid parameters
'403':
description: Forbidden - API key is invalid or not authorized
'429':
description: Too many requests - rate limit exceeded
'500':
description: Internal server error
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
LatLng:
type: object
description: A latitude/longitude coordinate pair
properties:
lat:
type: number
format: double
description: Latitude in decimal degrees
example: 37.4224764
lng:
type: number
format: double
description: Longitude in decimal degrees
example: -122.0842499
required:
- lat
- lng
AddressComponent:
type: object
description: An individual address component of a geocoding result
properties:
long_name:
type: string
description: The full text description of the address component
example: Mountain View
short_name:
type: string
description: An abbreviated textual name for the address component
example: MV
types:
type: array
description: Array indicating the type of the address component
items:
type: string
example:
- locality
- political
required:
- long_name
- short_name
- types
Bounds:
type: object
description: A bounding box defined by northeast and southwest corners
properties:
northeast:
$ref: '#/components/schemas/LatLng'
southwest:
$ref: '#/components/schemas/LatLng'
required:
- northeast
- southwest
GeocodingResponse:
type: object
description: The response from the Geocoding API
properties:
status:
type: string
description: Status code indicating the outcome of the request.
enum:
- OK
- ZERO_RESULTS
- OVER_DAILY_LIMIT
- OVER_QUERY_LIMIT
- REQUEST_DENIED
- INVALID_REQUEST
- UNKNOWN_ERROR
example: OK
results:
type: array
description: Array of geocoded address results
items:
$ref: '#/components/schemas/GeocodingResult'
example: []
error_message:
type: string
description: Human-readable description of the error, present when status is not OK.
example: example_value
required:
- status
- results
GeocodingResult:
type: object
description: A single geocoding result
properties:
address_components:
type: array
description: Array of address component objects
items:
$ref: '#/components/schemas/AddressComponent'
example: []
formatted_address:
type: string
description: The human-readable address of this location, composed from the individual address components.
example: 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
geometry:
$ref: '#/components/schemas/Geometry'
place_id:
type: string
description: A unique identifier for this place that can be used with other Google APIs.
example: ChIJ2eUgeAK6j4ARbn5u_wAGqWA
plus_code:
$ref: '#/components/schemas/PlusCode'
types:
type: array
description: Array of feature types describing the address component. See the list of supported types.
items:
type: string
example:
- street_address
partial_match:
type: boolean
description: Indicates that the geocoder did not return an exact match for the original request, though it was able to match part of the requested address.
example: true
required:
- address_components
- formatted_address
- geometry
- place_id
- types
Geometry:
type: object
description: Geometry information about the geocoding result
properties:
location:
$ref: '#/components/schemas/LatLng'
location_type:
type: string
description: The type of location returned. ROOFTOP indicates a precise geocode, RANGE_INTERPOLATED indicates an approximation between two precise points, GEOMETRIC_CENTER indicates a geometric center, and APPROXIMATE indicates an approximation.
enum:
- ROOFTOP
- RANGE_INTERPOLATED
- GEOMETRIC_CENTER
- APPROXIMATE
example: ROOFTOP
viewport:
$ref: '#/components/schemas/Bounds'
bounds:
$ref: '#/components/schemas/Bounds'
required:
- location
- location_type
- viewport
PlusCode:
type: object
description: An encoded location reference, derived from latitude and longitude coordinates, that represents an area. Plus codes can be used as a replacement for street addresses in places where they do not exist.
properties:
global_code:
type: string
description: The global (full) plus code consisting of area code and local code (e.g., 849VCWC8+R9).
example: 849VCWC8+R9
compound_code:
type: string
description: The compound plus code consisting of the local code and a locality description (e.g., CWC8+R9 Mountain View, CA, USA).
example: CWC8+R9 Mountain View, CA, USA
securitySchemes:
apiKey:
type: apiKey
name: key
in: query
description: Google Maps Platform API key
externalDocs:
description: Google Maps Directions API Documentation
url: https://developers.google.com/maps/documentation/directions/overview