openapi: 3.1.0
info:
title: Google Maps Geocoding API
description: >-
The Google Maps Geocoding API converts between addresses and geographic
coordinates. It supports forward geocoding (address to coordinates) and
reverse geocoding (coordinates to address). Results include formatted
addresses, address components, geometry with location coordinates, place
IDs, and location type classifications.
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
externalDocs:
description: Google Maps Geocoding API Documentation
url: https://developers.google.com/maps/documentation/geocoding/overview
servers:
- url: https://maps.googleapis.com/maps/api
description: Google Maps Geocoding 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:
securitySchemes:
apiKey:
type: apiKey
name: key
in: query
description: Google Maps Platform API key
schemas:
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
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
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
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
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
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"