From 715d6d56399eb10cf42c8132816226d15558ded2 Mon Sep 17 00:00:00 2001 From: Justin Poehnelt Date: Thu, 2 Sep 2021 19:21:28 +0000 Subject: [PATCH] fix: split docs for geocoding vs reverse geocoding --- .../maps_http_parameters_geocode.html | 15 +- .../maps_http_parameters_geocode.md | 13 +- .../maps_http_parameters_geocode_reverse.html | 249 ++++++++++++++++++ .../maps_http_parameters_geocode_reverse.md | 67 +++++ dist/google-maps-platform-openapi3.json | 61 ++++- dist/google-maps-platform-openapi3.yml | 81 +++++- dist/google-maps-platform-postman.json | 128 +++++---- generator/documentation/parameters.ts | 200 +++++++++----- specification/parameters/geocode/address.yml | 2 + specification/parameters/geocode/bounds.yml | 3 +- .../parameters/geocode/components.yml | 2 + .../parameters/geocode/location_type.yml | 33 +++ .../parameters/geocode/result_type.yml | 68 +++++ specification/paths/geocode.yml | 2 + 14 files changed, 775 insertions(+), 149 deletions(-) create mode 100644 dist/documentation/parameters/maps_http_parameters_geocode_reverse.html create mode 100644 dist/documentation/parameters/maps_http_parameters_geocode_reverse.md create mode 100644 specification/parameters/geocode/location_type.yml create mode 100644 specification/parameters/geocode/result_type.yml diff --git a/dist/documentation/parameters/maps_http_parameters_geocode.html b/dist/documentation/parameters/maps_http_parameters_geocode.html index 609019bb..45cbd95d 100644 --- a/dist/documentation/parameters/maps_http_parameters_geocode.html +++ b/dist/documentation/parameters/maps_http_parameters_geocode.html @@ -1,6 +1,6 @@ -

Optional parameters

+

Geocoding optional parameters

+
Note: One of `address` or `components` is required.

  • bounds

    The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, - results from the geocoder. - name: locations in: query + results from the geocoder.

  • @@ -46,6 +47,7 @@

    components

    provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder.

    +
    Note: One of `address` or `components` is required.

  • language

    @@ -87,15 +89,6 @@

    language

    • -
  • -

    latlng

    -

    - The street address that you want to geocode, in the format used by the - national postal service of the country concerned. Additional address - elements such as business names and unit, suite or floor numbers should be - avoided. -

    -

  • region

    diff --git a/dist/documentation/parameters/maps_http_parameters_geocode.md b/dist/documentation/parameters/maps_http_parameters_geocode.md index a88bb8da..cfaa462e 100644 --- a/dist/documentation/parameters/maps_http_parameters_geocode.md +++ b/dist/documentation/parameters/maps_http_parameters_geocode.md @@ -2,7 +2,7 @@ -

    Optional parameters

    +

    Geocoding optional parameters

    -

    address

    @@ -17,10 +17,11 @@ - global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`). - compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`). +
    Note: One of `address` or `components` is required.
    + -

    bounds

    - The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. - name: locations - in: query + The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. -

    components

    @@ -28,6 +29,8 @@ +
    Note: One of `address` or `components` is required.
    + -

    language

    The language in which to return results. @@ -38,10 +41,6 @@ - If a name is not available in the preferred language, the API uses the closest match. - The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, *utca* and *tér* are synonyms for street in Hungarian. --

    latlng

    - - The street address that you want to geocode, in the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. - -

    region

    The region code, specified as a [ccTLD ("top-level domain")](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains) two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland"). diff --git a/dist/documentation/parameters/maps_http_parameters_geocode_reverse.html b/dist/documentation/parameters/maps_http_parameters_geocode_reverse.html new file mode 100644 index 00000000..e58af6f9 --- /dev/null +++ b/dist/documentation/parameters/maps_http_parameters_geocode_reverse.html @@ -0,0 +1,249 @@ + + +

    + Reverse Geocoding required parameters +

    + +

    + Reverse Geocoding optional parameters +

    + +

    + Generated from the + OpenAPI specification. + edit Edit + bug_report Report bug +

    + + diff --git a/dist/documentation/parameters/maps_http_parameters_geocode_reverse.md b/dist/documentation/parameters/maps_http_parameters_geocode_reverse.md new file mode 100644 index 00000000..ba114093 --- /dev/null +++ b/dist/documentation/parameters/maps_http_parameters_geocode_reverse.md @@ -0,0 +1,67 @@ + + +

    Reverse Geocoding required parameters

    + +-

    latlng

    + + The street address that you want to geocode, in the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. + +

    Reverse Geocoding optional parameters

    + +-

    language

    + + The language in which to return results. + + - See the [list of supported languages](https://developers.google.com/maps/faq#languagesupport). Google often updates the supported languages, so this list may not be exhaustive. + - If `language` is not supplied, the API 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. + - The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component. + - If a name is not available in the preferred language, the API uses the closest match. + - The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, *utca* and *tér* are synonyms for street in Hungarian. + +-

    location_type

    + + A filter of one or more location types, separated by a pipe (`|`). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: The `location_type` parameter does not restrict the search to the specified location type(s). Rather, the `location_type` acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified location type(s). The following values are supported: + + - `APPROXIMATE` returns only the addresses that are characterized as approximate. + - `GEOMETRIC_CENTER` returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region). + - `RANGE_INTERPOLATED` returns only the addresses that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address. + - `ROOFTOP` returns only the addresses for which Google has location information accurate down to street address precision. + +-

    region

    + + The region code, specified as a [ccTLD ("top-level domain")](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains) two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland"). + +-

    result_type

    + + A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: The `result_type` parameter does not restrict the search to the specified address type(s). Rather, the `result_type` acts as a post-search filter: the API fetches all results for the specified `latlng`, then discards those results that do not match the specified address type(s).The following values are supported: + + - `administrative_area_level_1` indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level\_1 \* `short` names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data. + - `administrative_area_level_2` indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels. + - `administrative_area_level_3` indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + - `administrative_area_level_4` indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + - `administrative_area_level_5` indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + - `airport` indicates an airport. + - `colloquial_area` indicates a commonly-used alternative name for the entity. + - `country` indicates the national political entity, and is typically the highest order type returned by the Geocoder. + - `intersection` indicates a major intersection, usually of two major roads. + - `locality` indicates an incorporated city or town political entity. + - `natural_feature` indicates a prominent natural feature. + - `neighborhood` indicates a named neighborhood + - `park` indicates a named park. + - `plus_code` indicates an encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See for details. + - `point_of_interest` indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Empire State Building" or "Eiffel Tower". + - `political` indicates a political entity. Usually, this type indicates a polygon of some civil administration. + - `postal_code` indicates a postal code as used to address postal mail within the country. + - `premise` indicates a named location, usually a building or collection of buildings with a common name + - `route` indicates a named route (such as "US 101"). + - `street_address` indicates a precise street address. + - `sublocality` indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: `sublocality_level_1` to `sublocality_level_5`. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area. + - `subpremise` indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name + + +

    Generated from the OpenAPI specification. +edit Edit +bug_report Report bug +

    + + \ No newline at end of file diff --git a/dist/google-maps-platform-openapi3.json b/dist/google-maps-platform-openapi3.json index 0b105ed5..5796d43c 100755 --- a/dist/google-maps-platform-openapi3.json +++ b/dist/google-maps-platform-openapi3.json @@ -20683,7 +20683,7 @@ { "name": "address", "example": "1600 Amphitheatre+Parkway, Mountain View, CA", - "description": "The street address or plus code that you want 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 and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to `%20`):\n\n```\naddress=24%20Sussex%20Drive%20Ottawa%20ON\n```\n\nFormat plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`):\n- global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`).\n- compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`).", + "description": "The street address or plus code that you want 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 and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to `%20`):\n\n```\naddress=24%20Sussex%20Drive%20Ottawa%20ON\n```\n\nFormat plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`):\n- global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`).\n- compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`).\n\n
    Note: One of `address` or `components` is required.
    ", "in": "query", "schema": { "type": "string" @@ -20700,7 +20700,7 @@ "administrative_area_level_1:CA", "country:US" ], - "description": "A components filter with elements separated by a pipe (|). The components filter is also accepted as an optional parameter if an address is provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder.\n\nhttps://developers.google.com/maps/documentation/geocoding/overview#component-filtering", + "description": "A components filter with elements separated by a pipe (|). The components filter is also accepted as an optional parameter if an address is provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder.\n\nhttps://developers.google.com/maps/documentation/geocoding/overview#component-filtering\n\n
    Note: One of `address` or `components` is required.
    ", "in": "query", "schema": { "items": { @@ -20720,7 +20720,7 @@ }, { "name": "bounds", - "description": "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. - name: locations\nin: query", + "description": "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder.", "example": [ "35,-100", "40,-110" @@ -20730,6 +20730,61 @@ }, "in": "query" }, + { + "name": "result_type", + "description": "A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: The `result_type` parameter does not restrict the search to the specified address type(s). Rather, the `result_type` acts as a post-search filter: the API fetches all results for the specified `latlng`, then discards those results that do not match the specified address type(s).The following values are supported:\n* `administrative_area_level_1` indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 * `short` names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.\n* `administrative_area_level_2` indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.\n* `administrative_area_level_3` indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.\n* `administrative_area_level_4` indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.\n* `administrative_area_level_5` indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.\n* `airport` indicates an airport.\n* `colloquial_area` indicates a commonly-used alternative name for the entity.\n* `country` indicates the national political entity, and is typically the highest order type returned by the Geocoder.\n* `intersection` indicates a major intersection, usually of two major roads.\n* `locality` indicates an incorporated city or town political entity.\n* `natural_feature` indicates a prominent natural feature.\n* `neighborhood` indicates a named neighborhood\n* `park` indicates a named park.\n* `plus_code` indicates an encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See [https://plus.codes/](https://plus.codes/) for details.\n* `point_of_interest` indicates a named point of interest. Typically, these \"POI\"s are prominent local entities that don't easily fit in another category, such as \"Empire State Building\" or \"Eiffel Tower\".\n* `political` indicates a political entity. Usually, this type indicates a polygon of some civil administration.\n* `postal_code` indicates a postal code as used to address postal mail within the country.\n* `premise` indicates a named location, usually a building or collection of buildings with a common name\n* `route` indicates a named route (such as \"US 101\").\n* `street_address` indicates a precise street address.\n* `sublocality` indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: `sublocality_level_1` to `sublocality_level_5`. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area.\n* `subpremise` indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name", + "style": "pipeDelimited", + "explode": false, + "schema": { + "items": { + "type": "string", + "enum": [ + "administrative_area_level_1", + "administrative_area_level_2", + "administrative_area_level_3", + "administrative_area_level_4", + "administrative_area_level_5", + "airport", + "colloquial_area", + "country", + "intersection", + "locality", + "natural_feature", + "neighborhood", + "park", + "plus_code", + "political", + "postal_code", + "premise", + "route", + "street_address", + "sublocality", + "subpremise" + ] + }, + "type": "array" + }, + "in": "query" + }, + { + "name": "location_type", + "description": "A filter of one or more location types, separated by a pipe (`|`). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: The `location_type` parameter does not restrict the search to the specified location type(s). Rather, the `location_type` acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified location type(s). The following values are supported:\n* `APPROXIMATE` returns only the addresses that are characterized as approximate.\n* `GEOMETRIC_CENTER` returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region).\n* `RANGE_INTERPOLATED` returns only the addresses that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address.\n* `ROOFTOP` returns only the addresses for which Google has location information accurate down to street address precision.", + "style": "pipeDelimited", + "explode": false, + "schema": { + "items": { + "type": "string", + "enum": [ + "APPROXIMATE", + "GEOMETRIC_CENTER", + "RANGE_INTERPOLATED", + "ROOFTOP" + ] + }, + "type": "array" + }, + "in": "query" + }, { "$ref": "#/components/parameters/language" }, diff --git a/dist/google-maps-platform-openapi3.yml b/dist/google-maps-platform-openapi3.yml index 6711467d..4c082173 100755 --- a/dist/google-maps-platform-openapi3.yml +++ b/dist/google-maps-platform-openapi3.yml @@ -14658,6 +14658,8 @@ paths: Format plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`): - global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`). - compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`). + +
    Note: One of `address` or `components` is required.
    in: query schema: type: string @@ -14674,6 +14676,8 @@ paths: A components filter with elements separated by a pipe (|). The components filter is also accepted as an optional parameter if an address is provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder. https://developers.google.com/maps/documentation/geocoding/overview#component-filtering + +
    Note: One of `address` or `components` is required.
    in: query schema: items: @@ -14686,15 +14690,86 @@ paths: schema: type: string - name: bounds - description: |- - The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. - name: locations - in: query + description: 'The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder.' example: - '35,-100' - '40,-110' schema: $ref: '#/components/schemas/LatLngArrayString' in: query + - name: result_type + description: |- + A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: The `result_type` parameter does not restrict the search to the specified address type(s). Rather, the `result_type` acts as a post-search filter: the API fetches all results for the specified `latlng`, then discards those results that do not match the specified address type(s).The following values are supported: + * `administrative_area_level_1` indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 * `short` names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data. + * `administrative_area_level_2` indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels. + * `administrative_area_level_3` indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + * `administrative_area_level_4` indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + * `administrative_area_level_5` indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + * `airport` indicates an airport. + * `colloquial_area` indicates a commonly-used alternative name for the entity. + * `country` indicates the national political entity, and is typically the highest order type returned by the Geocoder. + * `intersection` indicates a major intersection, usually of two major roads. + * `locality` indicates an incorporated city or town political entity. + * `natural_feature` indicates a prominent natural feature. + * `neighborhood` indicates a named neighborhood + * `park` indicates a named park. + * `plus_code` indicates an encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See [https://plus.codes/](https://plus.codes/) for details. + * `point_of_interest` indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Empire State Building" or "Eiffel Tower". + * `political` indicates a political entity. Usually, this type indicates a polygon of some civil administration. + * `postal_code` indicates a postal code as used to address postal mail within the country. + * `premise` indicates a named location, usually a building or collection of buildings with a common name + * `route` indicates a named route (such as "US 101"). + * `street_address` indicates a precise street address. + * `sublocality` indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: `sublocality_level_1` to `sublocality_level_5`. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area. + * `subpremise` indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name + style: pipeDelimited + explode: false + schema: + items: + type: string + enum: + - administrative_area_level_1 + - administrative_area_level_2 + - administrative_area_level_3 + - administrative_area_level_4 + - administrative_area_level_5 + - airport + - colloquial_area + - country + - intersection + - locality + - natural_feature + - neighborhood + - park + - plus_code + - political + - postal_code + - premise + - route + - street_address + - sublocality + - subpremise + type: array + in: query + - name: location_type + description: |- + A filter of one or more location types, separated by a pipe (`|`). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: The `location_type` parameter does not restrict the search to the specified location type(s). Rather, the `location_type` acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified location type(s). The following values are supported: + * `APPROXIMATE` returns only the addresses that are characterized as approximate. + * `GEOMETRIC_CENTER` returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region). + * `RANGE_INTERPOLATED` returns only the addresses that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address. + * `ROOFTOP` returns only the addresses for which Google has location information accurate down to street address precision. + style: pipeDelimited + explode: false + schema: + items: + type: string + enum: + - APPROXIMATE + - GEOMETRIC_CENTER + - RANGE_INTERPOLATED + - ROOFTOP + type: array + in: query - $ref: '#/components/parameters/language' - $ref: '#/components/parameters/region' responses: diff --git a/dist/google-maps-platform-postman.json b/dist/google-maps-platform-postman.json index 9b0e6414..97fc0284 100755 --- a/dist/google-maps-platform-postman.json +++ b/dist/google-maps-platform-postman.json @@ -1,7 +1,7 @@ { "item": [ { - "id": "4d523c14-e94f-4933-8aac-12c42bfdf4cf", + "id": "0d9587a4-3aca-4a8b-a91d-07807f59c39c", "name": "Directions API", "description": { "content": "The Directions API is a web service that uses an HTTP request to return JSON or XML-formatted directions between locations. You can receive directions for several modes of transportation, such as transit, driving, walking, or cycling.", @@ -9,7 +9,7 @@ }, "item": [ { - "id": "f60056ec-e4de-4ac1-86b3-580d6543876f", + "id": "e3770feb-b5fd-4745-a299-1cb02e063cf2", "name": "/maps/api/directions/json", "request": { "name": "/maps/api/directions/json", @@ -123,7 +123,7 @@ }, "response": [ { - "id": "c6641975-be1b-4ed7-affe-fac78e3da6b1", + "id": "317e7c83-b312-4687-b1a2-c34f54e07e6b", "name": "200 OK", "originalRequest": { "url": { @@ -216,7 +216,7 @@ "event": [] }, { - "id": "b8b6f9b5-3db6-499c-b06b-21391a38ef30", + "id": "1d4c9a5e-9c0c-4f7a-b241-9591b259ae59", "name": "Distance Matrix API", "description": { "content": "The Distance Matrix API is a service that provides travel distance and time for a matrix of origins and destinations.", @@ -224,7 +224,7 @@ }, "item": [ { - "id": "57c10bde-a1e4-48a3-8162-b27347983607", + "id": "ca1893ef-4c1c-458a-9951-f2949bb98703", "name": "/maps/api/distanceMatrix/json", "request": { "name": "/maps/api/distanceMatrix/json", @@ -326,7 +326,7 @@ }, "response": [ { - "id": "f645125a-d8ad-410e-9e2d-96c6aa63afd5", + "id": "44751f03-6da2-434b-886b-4e12304e2a90", "name": "200 OK", "originalRequest": { "url": { @@ -411,7 +411,7 @@ "event": [] }, { - "id": "3baecd27-e284-45f5-a4ba-2f2a75f481f8", + "id": "5f974094-821a-48ab-93b6-6a8bbaedfa38", "name": "Elevation API", "description": { "content": "The Elevation API provides a simple interface to query locations on the earth for elevation data. Additionally, you may request sampled elevation data along paths, allowing you to calculate elevation changes along routes.", @@ -419,7 +419,7 @@ }, "item": [ { - "id": "9c52f824-72b4-44d9-b9ec-1986cca03988", + "id": "c5589d29-af5a-4478-ab3a-05de42c6dff5", "name": "/maps/api/elevation/json", "request": { "name": "/maps/api/elevation/json", @@ -467,7 +467,7 @@ }, "response": [ { - "id": "2ee34e38-7a53-47e1-9ba8-6c3a181d5bd6", + "id": "7fb1fe48-9774-4008-b61d-9ecfaef5715e", "name": "200 OK", "originalRequest": { "url": { @@ -516,7 +516,7 @@ "event": [] }, { - "id": "f4da9689-19f7-4ace-b140-aea1bfaa0e45", + "id": "6f5de413-1961-4320-aec9-c6e28c06fa40", "name": "Geocoding API", "description": { "content": "The Geocoding API is a service that provides geocoding and reverse geocoding of addresses.", @@ -524,7 +524,7 @@ }, "item": [ { - "id": "3b76a674-aba1-4827-a29c-46b97b082bf3", + "id": "f266007e-7db6-4edf-8328-6881a7aecef5", "name": "/maps/api/geocode/json", "request": { "name": "/maps/api/geocode/json", @@ -550,13 +550,13 @@ "disabled": true, "key": "address", "value": "", - "description": "The street address or plus code that you want 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 and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to `%20`):\n\n```\naddress=24%20Sussex%20Drive%20Ottawa%20ON\n```\n\nFormat plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`):\n- global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`).\n- compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`)." + "description": "The street address or plus code that you want 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 and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to `%20`):\n\n```\naddress=24%20Sussex%20Drive%20Ottawa%20ON\n```\n\nFormat plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`):\n- global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`).\n- compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`).\n\n
    Note: One of `address` or `components` is required.
    " }, { "disabled": true, "key": "components", "value": "|", - "description": "A components filter with elements separated by a pipe (|). The components filter is also accepted as an optional parameter if an address is provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder.\n\nhttps://developers.google.com/maps/documentation/geocoding/overview#component-filtering" + "description": "A components filter with elements separated by a pipe (|). The components filter is also accepted as an optional parameter if an address is provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder.\n\nhttps://developers.google.com/maps/documentation/geocoding/overview#component-filtering\n\n
    Note: One of `address` or `components` is required.
    " }, { "disabled": true, @@ -568,13 +568,25 @@ "disabled": true, "key": "bounds", "value": "", - "description": "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. - name: locations\nin: query" + "description": "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder." }, { "disabled": true, "key": "bounds", "value": "", - "description": "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. - name: locations\nin: query" + "description": "The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder." + }, + { + "disabled": true, + "key": "result_type", + "value": "|", + "description": "A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: The `result_type` parameter does not restrict the search to the specified address type(s). Rather, the `result_type` acts as a post-search filter: the API fetches all results for the specified `latlng`, then discards those results that do not match the specified address type(s).The following values are supported:\n* `administrative_area_level_1` indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 * `short` names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.\n* `administrative_area_level_2` indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.\n* `administrative_area_level_3` indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.\n* `administrative_area_level_4` indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.\n* `administrative_area_level_5` indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.\n* `airport` indicates an airport.\n* `colloquial_area` indicates a commonly-used alternative name for the entity.\n* `country` indicates the national political entity, and is typically the highest order type returned by the Geocoder.\n* `intersection` indicates a major intersection, usually of two major roads.\n* `locality` indicates an incorporated city or town political entity.\n* `natural_feature` indicates a prominent natural feature.\n* `neighborhood` indicates a named neighborhood\n* `park` indicates a named park.\n* `plus_code` indicates an encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See [https://plus.codes/](https://plus.codes/) for details.\n* `point_of_interest` indicates a named point of interest. Typically, these \"POI\"s are prominent local entities that don't easily fit in another category, such as \"Empire State Building\" or \"Eiffel Tower\".\n* `political` indicates a political entity. Usually, this type indicates a polygon of some civil administration.\n* `postal_code` indicates a postal code as used to address postal mail within the country.\n* `premise` indicates a named location, usually a building or collection of buildings with a common name\n* `route` indicates a named route (such as \"US 101\").\n* `street_address` indicates a precise street address.\n* `sublocality` indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: `sublocality_level_1` to `sublocality_level_5`. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area.\n* `subpremise` indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name" + }, + { + "disabled": true, + "key": "location_type", + "value": "|", + "description": "A filter of one or more location types, separated by a pipe (`|`). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: The `location_type` parameter does not restrict the search to the specified location type(s). Rather, the `location_type` acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified location type(s). The following values are supported:\n* `APPROXIMATE` returns only the addresses that are characterized as approximate.\n* `GEOMETRIC_CENTER` returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region).\n* `RANGE_INTERPOLATED` returns only the addresses that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address.\n* `ROOFTOP` returns only the addresses for which Google has location information accurate down to street address precision." }, { "disabled": true, @@ -596,7 +608,7 @@ }, "response": [ { - "id": "76ac7f96-150a-4da2-8335-5c7d2ad8e37d", + "id": "474766cf-f1e7-4d25-9806-594dbcbc2798", "name": "200 OK", "originalRequest": { "url": { @@ -624,6 +636,14 @@ "key": "bounds", "value": "40,-110" }, + { + "key": "result_type", + "value": "|" + }, + { + "key": "location_type", + "value": "|" + }, { "key": "language", "value": "en" @@ -661,7 +681,7 @@ "event": [] }, { - "id": "37d8b1f0-2f3c-4957-a3c2-3315ad05ccbd", + "id": "e4eefbea-1126-47e9-9125-ddebd8ca2c4d", "name": "Geolocation API", "description": { "content": "The Geolocation API returns a location and accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect.", @@ -669,7 +689,7 @@ }, "item": [ { - "id": "f11166f4-1581-4b53-8674-167be5dcf03a", + "id": "830ea9a1-5083-468b-b3d5-7d37889c4137", "name": "/geolocation/v1/geolocate", "request": { "name": "/geolocation/v1/geolocate", @@ -707,7 +727,7 @@ }, "response": [ { - "id": "cf02b30f-48fd-4bb0-85ae-acabc838d3d8", + "id": "6c35ec07-ba84-4d8f-b70e-34600dfe61d1", "name": "200 OK", "originalRequest": { "url": { @@ -741,7 +761,7 @@ "_postman_previewlanguage": "json" }, { - "id": "2720433b-5fc9-4e36-8fab-a42b4a4e3f23", + "id": "170fa172-5d49-485f-b5a2-bfae28e99b40", "name": "400 BAD REQUEST", "originalRequest": { "url": { @@ -775,7 +795,7 @@ "_postman_previewlanguage": "json" }, { - "id": "c47f5d52-7a9c-4fdc-bb7f-42f030a98095", + "id": "183801b4-3e71-4832-84dc-ebaf444279b3", "name": "404 NOT FOUND", "originalRequest": { "url": { @@ -815,7 +835,7 @@ "event": [] }, { - "id": "a5eb42e6-d41d-4710-9f7f-6ea90bdf8610", + "id": "410e59e7-268b-41b8-b5bc-65aa142bec42", "name": "Roads API", "description": { "content": "The Roads API identifies the roads a vehicle was traveling along and provides additional metadata about those roads, such as speed limits.", @@ -823,7 +843,7 @@ }, "item": [ { - "id": "14a38bac-07f3-4735-b0c3-4a3085e44e60", + "id": "f98362e0-8ac2-4ee3-aeb5-01fb058ca1bd", "name": "/v1/snapToRoads", "request": { "name": "/v1/snapToRoads", @@ -863,7 +883,7 @@ }, "response": [ { - "id": "21e56d7f-b759-4f17-ae08-45989edb0f1f", + "id": "f0e23d46-3d60-41a2-9238-6c3fd0192123", "name": "200 OK", "originalRequest": { "url": { @@ -905,7 +925,7 @@ "event": [] }, { - "id": "7445e218-3c49-4308-a693-2d2720080e2e", + "id": "a9c70c55-6df3-4bb7-a4ef-0032de4e4ab4", "name": "/v1/nearestRoads", "request": { "name": "/v1/nearestRoads", @@ -939,7 +959,7 @@ }, "response": [ { - "id": "5578d2ed-2dd7-464d-b606-574e4146b62f", + "id": "d6b8a71e-f1b0-480a-9a89-efb13b6e0d92", "name": "200 OK", "originalRequest": { "url": { @@ -969,12 +989,12 @@ "value": "application/json" } ], - "body": "{\n \"snappedPoints\": [\n {\n \"location\": {\n \"latitude\": -43188299.63533428,\n \"longitude\": -67291571.3561348\n },\n \"placeId\": \"aliqua adipisicing\",\n \"originalIndex\": -5911440.554061413\n },\n {\n \"location\": {\n \"latitude\": -39389201.359791756,\n \"longitude\": -96229869.42020044\n },\n \"placeId\": \"consectetur incididunt\",\n \"originalIndex\": 50739249.83588633\n }\n ]\n}", + "body": "{\n \"snappedPoints\": [\n {\n \"location\": {\n \"latitude\": -78817186.21111488,\n \"longitude\": 2203503.7009748816\n },\n \"placeId\": \"do\",\n \"originalIndex\": 27891297.913361117\n },\n {\n \"location\": {\n \"latitude\": -37073949.4294158,\n \"longitude\": 20200139.40790446\n },\n \"placeId\": \"in ali\",\n \"originalIndex\": -65231134.40601116\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { - "id": "71745e37-2f60-48cc-9627-b7750df4cba4", + "id": "d6dc1e81-9354-44ef-9097-493f20b2727c", "name": "400 BAD REQUEST", "originalRequest": { "url": { @@ -1015,7 +1035,7 @@ "event": [] }, { - "id": "3c4dd4df-2475-4983-addb-f1ba5bdb64d2", + "id": "88e0d05b-97c8-4625-9a73-597be4b74da4", "name": "Time Zone API", "description": { "content": "The Time Zone API provides a simple interface to request the time zone for locations on the surface of the earth, as well as the time offset from UTC for each of those locations.", @@ -1023,7 +1043,7 @@ }, "item": [ { - "id": "23d4c555-77b6-44c3-a4e8-1c20e8d6483d", + "id": "45e27053-4373-4ec2-9b80-2e6bc6a2a9ba", "name": "/maps/api/timezone/json", "request": { "name": "/maps/api/timezone/json", @@ -1071,7 +1091,7 @@ }, "response": [ { - "id": "152b6727-ebf7-4f46-bec0-971ab3219c5f", + "id": "709658fc-5407-44ef-84cc-c4790befff33", "name": "200 OK", "originalRequest": { "url": { @@ -1120,7 +1140,7 @@ "event": [] }, { - "id": "f7d710ff-3a7d-4dff-a6f0-7245e6b9b6f9", + "id": "a7de65d6-cd65-495c-ba57-760c18a6503c", "name": "Street View API", "description": { "content": "The Street View API provides a simple interface to retrieve Street View images.", @@ -1128,7 +1148,7 @@ }, "item": [ { - "id": "38e3be0d-397e-422d-aaae-3bb1dcf98558", + "id": "107780bf-5b21-46a4-9e25-674db24e6889", "name": "/maps/api/streetview", "request": { "name": "/maps/api/streetview", @@ -1217,7 +1237,7 @@ }, "response": [ { - "id": "bfef4e55-8f2b-4ddc-aa1f-3ed84cb28727", + "id": "deb8ec0b-57f6-4799-9db9-31cd4b7bb680", "name": "200 OK", "originalRequest": { "url": { @@ -1283,7 +1303,7 @@ "value": "image/*" } ], - "body": "consequat minim tempor in", + "body": "exercitation est Ut", "cookie": [], "_postman_previewlanguage": "text" } @@ -1291,7 +1311,7 @@ "event": [] }, { - "id": "dde3a086-eb89-4094-9124-0c0f1b2baf92", + "id": "2c03a1d9-429e-447d-aebc-21ab39b92769", "name": "/maps/api/streetview/metadata", "request": { "name": "/maps/api/streetview/metadata", @@ -1375,7 +1395,7 @@ }, "response": [ { - "id": "13c4b6a8-f02a-42a4-b4e7-3302e484630d", + "id": "8c703fa1-a909-4dea-aee5-97e2b113f430", "name": "200 OK", "originalRequest": { "url": { @@ -1448,7 +1468,7 @@ "event": [] }, { - "id": "c31f4b0a-7119-492a-9d01-6594e36969cd", + "id": "07263ff0-9406-4bd5-9fb0-8bf79a007694", "name": "Places API", "description": { "content": "The Places API is a service that returns information about places using HTTP requests. Places are defined within this API as establishments, geographic locations, or prominent points of interest.", @@ -1456,7 +1476,7 @@ }, "item": [ { - "id": "83f8e7ff-f346-4c64-b392-b247b1e252c8", + "id": "057557e5-8cb5-4802-a0b5-30a78ff63e77", "name": "/maps/api/place/details/json", "request": { "name": "/maps/api/place/details/json", @@ -1517,7 +1537,7 @@ }, "response": [ { - "id": "c6ac267e-cde1-4f1f-9206-243ca5b38705", + "id": "f3171b80-4832-4915-a8fc-b12e88a4f682", "name": "200 OK", "originalRequest": { "url": { @@ -1571,7 +1591,7 @@ "event": [] }, { - "id": "71dbb686-b81b-401b-b9b2-b0041e0473fe", + "id": "4eaba876-1930-4d29-bbe4-115ef68515a3", "name": "/maps/api/place/findplacefromtext/json", "request": { "name": "/maps/api/place/findplacefromtext/json", @@ -1632,7 +1652,7 @@ }, "response": [ { - "id": "4e9d852e-2f97-47c5-b7ab-29632aa2e44d", + "id": "2bda2f2e-a182-44eb-b9fd-3c8e95d1c81b", "name": "200 OK", "originalRequest": { "url": { @@ -1686,7 +1706,7 @@ "event": [] }, { - "id": "b5003f11-af32-4b24-b476-b28d64fcba1e", + "id": "c5a01961-dfa3-47bf-a14d-0ef524d41d4c", "name": "/maps/api/place/nearbysearch/json", "request": { "name": "/maps/api/place/nearbysearch/json", @@ -1783,7 +1803,7 @@ }, "response": [ { - "id": "b7823f69-a2d1-49eb-9602-30885cf25110", + "id": "3660f14f-19ca-4df4-8db5-6a710f3eb321", "name": "200 OK", "originalRequest": { "url": { @@ -1861,7 +1881,7 @@ "event": [] }, { - "id": "9a1ccbf6-df33-4b96-8e30-36dfc14ea741", + "id": "ab4128ca-c709-4430-8de2-b34b2c8fe269", "name": "/maps/api/place/textsearch/json", "request": { "name": "/maps/api/place/textsearch/json", @@ -1952,7 +1972,7 @@ }, "response": [ { - "id": "893de4a3-8b18-43cb-9136-8dbd2bb84157", + "id": "cfc56998-5f66-42cc-9965-60aa33e1f499", "name": "200 OK", "originalRequest": { "url": { @@ -2026,7 +2046,7 @@ "event": [] }, { - "id": "05c65204-a0d8-4ea2-a5cb-f019ad7ec513", + "id": "1b263274-d488-41e9-a5dd-6147e3a00ee1", "name": "/maps/api/place/photo", "request": { "name": "/maps/api/place/photo", @@ -2074,7 +2094,7 @@ }, "response": [ { - "id": "40610705-83d1-475f-ace8-ae3574fb4b92", + "id": "544fb7aa-14e5-4792-8f69-bd98a892d89c", "name": "200 OK", "originalRequest": { "url": { @@ -2112,7 +2132,7 @@ "value": "image/*" } ], - "body": "consequat minim tempor in", + "body": "exercitation est Ut", "cookie": [], "_postman_previewlanguage": "text" } @@ -2120,7 +2140,7 @@ "event": [] }, { - "id": "3a345042-63f8-402e-805d-2708789e3165", + "id": "e0104210-795f-42f7-b264-b8eb6cf12a0c", "name": "/maps/api/place/queryautocomplete/json", "request": { "name": "/maps/api/place/queryautocomplete/json", @@ -2181,7 +2201,7 @@ }, "response": [ { - "id": "fc0c82d3-1b66-4400-802f-11797836014f", + "id": "83498349-c4cc-436c-8c38-0626fa0bad78", "name": "200 OK", "originalRequest": { "url": { @@ -2235,7 +2255,7 @@ "event": [] }, { - "id": "7ef22243-ac84-4399-95ff-1b1b2784eb13", + "id": "640ca4a9-b31b-4efe-9b80-ca90ed658517", "name": "/maps/api/place/autocomplete/json", "request": { "name": "/maps/api/place/autocomplete/json", @@ -2326,7 +2346,7 @@ }, "response": [ { - "id": "015626ec-26bb-44e0-a057-089c335edc33", + "id": "55c3aee2-98b0-455b-806f-f96d9d185671", "name": "200 OK", "originalRequest": { "url": { @@ -2429,7 +2449,7 @@ ] }, "info": { - "_postman_id": "f51e54ff-d59b-4530-904b-dc99b355fed4", + "_postman_id": "6f2702dd-c9d8-45b5-ab0f-04cf1157b3fe", "name": "Google Maps Platform", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { diff --git a/generator/documentation/parameters.ts b/generator/documentation/parameters.ts index 91edccb1..9b66711a 100644 --- a/generator/documentation/parameters.ts +++ b/generator/documentation/parameters.ts @@ -29,7 +29,7 @@ import { list, listItem, } from "mdast-builder"; -import { Parent } from "unist"; +import { Node, Parent } from "unist"; import { feedbackLinks } from "./helpers"; const argv = options({ @@ -43,7 +43,7 @@ const argv = options({ }, }).argv; -const build = (p: OpenAPIV3.ParameterObject): Parent => { +const buildParameterListItem = (p: OpenAPIV3.ParameterObject): Parent => { const nodes: any = []; nodes.push(htmlNode(`

    ${p.name}

    `)); @@ -54,6 +54,66 @@ const build = (p: OpenAPIV3.ParameterObject): Parent => { return listItem(nodes); }; +const build = ( + key: string, + regionTag: string, + parameters: OpenAPIV3.ParameterObject[], + options: { requiredHeading: string; optionalHeading: string } = { + requiredHeading: "Required parameters", + optionalHeading: "Optional parameters", + } +): Node[] => { + const nodes: any = []; + + parameters.sort( + (a: OpenAPIV3.ParameterObject, b: OpenAPIV3.ParameterObject) => { + if (a.required && b.required) { + return a.name < b.name ? -1 : 1; + } else if (a.required) { + return -1; + } else if (b.required) { + return 1; + } else { + return a.name < b.name ? -1 : 1; + } + } + ); + + const required = parameters.filter( + (p: OpenAPIV3.ParameterObject) => p.required + ); + + const optional = parameters.filter( + (p: OpenAPIV3.ParameterObject) => !p.required + ); + + if (required.length) { + nodes.push( + htmlNode( + `

    ${ + options.requiredHeading + }

    ` + ) + ); + } + nodes.push(list("unordered", required.map(buildParameterListItem))); + + if (optional.length) { + nodes.push( + htmlNode( + `

    ${ + options.optionalHeading + }

    ` + ) + ); + } + + nodes.push(list("unordered", optional.map(buildParameterListItem))); + + nodes.push(feedbackLinks(key, "parameters", regionTag)); + + return nodes; +}; const main = async (argv: any) => { const spec = (await $RefParser.dereference( JSON.parse(readFileSync(argv.spec).toString()) as OpenAPIV3.Document @@ -61,76 +121,78 @@ const main = async (argv: any) => { const pack = tar.pack(); + async function write(nodes: Node[], regionTag: string) { + const markdown = mdProcessor.stringify(root(nodes)); + // write markdown file + pack.entry( + { + name: `documentation/parameters/${regionTag}.md`, + }, + `\n\n${markdown}\n` + ); + + const html = await htmlProcessor.process(markdown); + // write html file + pack.entry( + { + name: `documentation/parameters/${regionTag}.html`, + }, + prettier.format( + `\n\n${html}\n`, + { parser: "html" } + ) + ); + } + for (const key in spec.paths!) { - const path = spec.paths![key]; - for (const method in path) { - const { parameters } = path[method]; - - if (parameters) { - const regionTag = `maps_http_parameters_${slugify(key) - .toLowerCase() - .replace(/(v1|mapsapi|json)/g, "")}`; - const nodes: any = []; - - parameters.sort( - (a: OpenAPIV3.ParameterObject, b: OpenAPIV3.ParameterObject) => { - if (a.required && b.required) { - return a.name < b.name ? -1 : 1; - } else if (a.required) { - return -1; - } else if (b.required) { - return 1; - } else { - return a.name < b.name ? -1 : 1; + // Custom handling for geocoding and reverse geocoding + if (key === "/maps/api/geocode/json") { + const parameters = spec.paths![key]!.get! + .parameters! as OpenAPIV3.ParameterObject[]; + const geocode = { + regionTag: "maps_http_parameters_geocode", + parameters: parameters.filter( + (p) => !["latlng", "result_type", "location_type"].includes(p.name) + ), + options: { + requiredHeading: "Geocoding required parameters", + optionalHeading: "Geocoding optional parameters", + }, + }; + + const reverseGeocode = { + regionTag: "maps_http_parameters_geocode_reverse", + parameters: parameters + .filter((p) => !["components", "address", "bounds"].includes(p.name)) + .map((p) => { + if (p.name === "latlng") { + p.required = true; } - } - ); - - const required = parameters.filter( - (p: OpenAPIV3.ParameterObject) => p.required - ); - - const optional = parameters.filter( - (p: OpenAPIV3.ParameterObject) => !p.required - ); - - if (required.length) { - nodes.push( - htmlNode('

    Required parameters

    ') - ); + return p; + }), + options: { + requiredHeading: "Reverse Geocoding required parameters", + optionalHeading: "Reverse Geocoding optional parameters", + }, + }; + + [geocode, reverseGeocode].forEach(async ({ regionTag, parameters, options }) => { + const nodes = build(key, regionTag, parameters, options); + await write(nodes, regionTag); + }); + } else { + const path = spec.paths![key]; + for (const method in path) { + const { parameters } = path[method]; + + if (parameters) { + const regionTag = `maps_http_parameters_${slugify(key) + .toLowerCase() + .replace(/(v1|mapsapi|json)/g, "")}`; + const nodes = build(key, regionTag, parameters); + + await write(nodes, regionTag); } - nodes.push(list("unordered", required.map(build))); - - if (optional.length) { - nodes.push( - htmlNode('

    Optional parameters

    ') - ); - } - - nodes.push(list("unordered", optional.map(build))); - - nodes.push(feedbackLinks(key, "parameters", regionTag)); - - const markdown = mdProcessor.stringify(root(nodes)); - // write markdown file - pack.entry( - { - name: `documentation/parameters/${regionTag}.md`, - }, - `\n\n${markdown}\n` - ); - - const html = await htmlProcessor.process(markdown); - // write html file - pack.entry( - { - name: `documentation/parameters/${regionTag}.html`, - }, - prettier.format( - `\n\n${html}\n`, - { parser: "html" } - ) - ); } } } diff --git a/specification/parameters/geocode/address.yml b/specification/parameters/geocode/address.yml index 65b9a7fe..3ecd67c1 100644 --- a/specification/parameters/geocode/address.yml +++ b/specification/parameters/geocode/address.yml @@ -24,6 +24,8 @@ description: |- Format plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`): - global code is a 4 character area code and 6 character or longer local code (`849VCWC8+R9` is `849VCWC8%2BR9`). - compound code is a 6 character or longer local code with an explicit location (`CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`). + +
    Note: One of `address` or `components` is required.
    in: query schema: type: string \ No newline at end of file diff --git a/specification/parameters/geocode/bounds.yml b/specification/parameters/geocode/bounds.yml index d35d7793..f5a2fa7d 100644 --- a/specification/parameters/geocode/bounds.yml +++ b/specification/parameters/geocode/bounds.yml @@ -14,8 +14,7 @@ name: bounds description: |- - The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. - name: locations - in: query + The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. example: - "35,-100" - "40,-110" diff --git a/specification/parameters/geocode/components.yml b/specification/parameters/geocode/components.yml index 02f3bbfd..09462a55 100644 --- a/specification/parameters/geocode/components.yml +++ b/specification/parameters/geocode/components.yml @@ -27,6 +27,8 @@ description: |- A components filter with elements separated by a pipe (|). The components filter is also accepted as an optional parameter if an address is provided. Each element in the components filter consists of a component:value pair, and fully restricts the results from the geocoder. https://developers.google.com/maps/documentation/geocoding/overview#component-filtering + +
    Note: One of `address` or `components` is required.
    in: query schema: items: diff --git a/specification/parameters/geocode/location_type.yml b/specification/parameters/geocode/location_type.yml new file mode 100644 index 00000000..0f7195b0 --- /dev/null +++ b/specification/parameters/geocode/location_type.yml @@ -0,0 +1,33 @@ +# Copyright 2021 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: location_type +description: |- + A filter of one or more location types, separated by a pipe (`|`). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: The `location_type` parameter does not restrict the search to the specified location type(s). Rather, the `location_type` acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified location type(s). The following values are supported: + * `APPROXIMATE` returns only the addresses that are characterized as approximate. + * `GEOMETRIC_CENTER` returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region). + * `RANGE_INTERPOLATED` returns only the addresses that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address. + * `ROOFTOP` returns only the addresses for which Google has location information accurate down to street address precision. +style: pipeDelimited +explode: false +schema: + items: + type: string + enum: + - APPROXIMATE + - GEOMETRIC_CENTER + - RANGE_INTERPOLATED + - ROOFTOP + type: array +in: query \ No newline at end of file diff --git a/specification/parameters/geocode/result_type.yml b/specification/parameters/geocode/result_type.yml new file mode 100644 index 00000000..06a0ec5c --- /dev/null +++ b/specification/parameters/geocode/result_type.yml @@ -0,0 +1,68 @@ +# Copyright 2021 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: result_type +description: |- + A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: The `result_type` parameter does not restrict the search to the specified address type(s). Rather, the `result_type` acts as a post-search filter: the API fetches all results for the specified `latlng`, then discards those results that do not match the specified address type(s).The following values are supported: + * `administrative_area_level_1` indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 * `short` names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data. + * `administrative_area_level_2` indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels. + * `administrative_area_level_3` indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + * `administrative_area_level_4` indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + * `administrative_area_level_5` indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. + * `airport` indicates an airport. + * `colloquial_area` indicates a commonly-used alternative name for the entity. + * `country` indicates the national political entity, and is typically the highest order type returned by the Geocoder. + * `intersection` indicates a major intersection, usually of two major roads. + * `locality` indicates an incorporated city or town political entity. + * `natural_feature` indicates a prominent natural feature. + * `neighborhood` indicates a named neighborhood + * `park` indicates a named park. + * `plus_code` indicates an encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See [https://plus.codes/](https://plus.codes/) for details. + * `point_of_interest` indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Empire State Building" or "Eiffel Tower". + * `political` indicates a political entity. Usually, this type indicates a polygon of some civil administration. + * `postal_code` indicates a postal code as used to address postal mail within the country. + * `premise` indicates a named location, usually a building or collection of buildings with a common name + * `route` indicates a named route (such as "US 101"). + * `street_address` indicates a precise street address. + * `sublocality` indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: `sublocality_level_1` to `sublocality_level_5`. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area. + * `subpremise` indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name +style: pipeDelimited +explode: false +schema: + items: + type: string + enum: + - administrative_area_level_1 + - administrative_area_level_2 + - administrative_area_level_3 + - administrative_area_level_4 + - administrative_area_level_5 + - airport + - colloquial_area + - country + - intersection + - locality + - natural_feature + - neighborhood + - park + - plus_code + - political + - postal_code + - premise + - route + - street_address + - sublocality + - subpremise + type: array +in: query \ No newline at end of file diff --git a/specification/paths/geocode.yml b/specification/paths/geocode.yml index 40110956..5a345f5c 100644 --- a/specification/paths/geocode.yml +++ b/specification/paths/geocode.yml @@ -31,6 +31,8 @@ parameters: - "$ref": "../parameters/geocode/components.yml" - "$ref": "../parameters/geocode/latlng.yml" - "$ref": "../parameters/geocode/bounds.yml" + - "$ref": "../parameters/geocode/result_type.yml" + - "$ref": "../parameters/geocode/location_type.yml" - "$ref": "../parameters/language.yml" - "$ref": "../parameters/region.yml" responses: