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"