update description of geocoding api (Azure#23101)

chcmsft · aviyerMSFT · commit c4bd4324e309 · 2023-03-22T13:36:09.000-07:00
diff --git a/specification/maps/data-plane/Search/preview/2022-09-01-preview/search.json b/specification/maps/data-plane/Search/preview/2022-09-01-preview/search.json
@@ -375,7 +375,7 @@
     },
     "/geocode/batch": {
       "post": {
-        "description": "**Geocoding Batch API**\n\n\n**Applies to**: see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\n\n\nThe Geocoding Batch API sends batches of queries to [Geocoding API](https://docs.microsoft.com/en-us/rest/api/maps/search-v2/get-geocoding) using just a single API call. The API allows caller to batch up to **100** queries.\n>[!Important]\n>By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/) for additional details.\n\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/geocode/batch?api-version=2022-02-01-preview\n```\n### POST Body for Batch Request\nTo send the _geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _geocoding_ queries:\n\n\n```\n{\n  \"batchItems\": [\n    {\n      \"addressLine\": \"One, Microsoft Way, Redmond, WA 98052\",\n      \"top\": 2\n    },\n    {\n      \"addressLine\": \"Pike Pl\",\n      \"adminDistrict\": \"WA\",\n      \"locality\": \"Seattle\",\n      \"top\": 3\n    }\n  ]\n}\n```\n\nA _geocoding_ batchItem object can accept any of the supported _geocoding_ [URI parameters](https://docs.microsoft.com/en-us/rest/api/maps/search-v2/get-geocoding#uri-parameters) except query.\n\n\nThe batch should contain at least **1** query.\n\n\n### Batch Response Model\nThe batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:\n\n  - [`GeocodingResponse`](https://docs.microsoft.com/en-us/rest/api/maps/search-v2/get-geocoding#geocodingresponse) - If the query completed successfully.\n\n  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\n",
+        "description": "**Geocoding Batch API**\n\n\n**Applies to**: see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\n\n\nThe Geocoding Batch API sends batches of queries to [Geocoding API](https://docs.microsoft.com/en-us/rest/api/maps/search-v2/get-geocoding) using just a single API call. The API allows caller to batch up to **100** queries.\n>[!Important]\n>By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/) for additional details.\n\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/geocode/batch?api-version=2022-09-01-preview\n```\n### POST Body for Batch Request\nTo send the _geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _geocoding_ queries:\n\n\n```\n{\n  \"batchItems\": [\n    {\n      \"addressLine\": \"One, Microsoft Way, Redmond, WA 98052\",\n      \"top\": 2\n    },\n    {\n      \"addressLine\": \"Pike Pl\",\n      \"adminDistrict\": \"WA\",\n      \"locality\": \"Seattle\",\n      \"top\": 3\n    }\n  ]\n}\n```\n\nA _geocoding_ batchItem object can accept any of the supported _geocoding_ [URI parameters](https://docs.microsoft.com/en-us/rest/api/maps/search-v2/get-geocoding#uri-parameters) except query.\n\n\nThe batch should contain at least **1** query.\n\n\n### Batch Response Model\nThe batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:\n\n  - [`GeocodingResponse`](https://docs.microsoft.com/en-us/rest/api/maps/search-v2/get-geocoding#geocodingresponse) - If the query completed successfully.\n\n  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\n",
         "operationId": "Search_GetGeocodingBatch",
         "x-ms-examples": {
           "A Geocoding Batch API call containing 2 Geocoding queries": {
@@ -512,7 +512,7 @@
             "$ref": "../../../Common/preview/2022-09-01-preview/common.json#/definitions/GeoJsonPoint"
           },
           "calculationMethod": {
-            "description": "The method that was used to compute the geocode point.\n- `Interpolation`: The geocode point was matched to a point on a road using interpolation.\n- `InterpolationOffset`: The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street.\n- `Parcel`: The geocode point was matched to the center of a parcel.\n- `Rooftop`: The geocode point was matched to the rooftop of a building.",
+            "description": "The method that was used to compute the geocode point.",
             "type": "string",
             "enum": [
               "Interpolation",
@@ -525,16 +525,20 @@
               "modelAsString": true,
               "values": [
                 {
-                  "value": "Interpolation"
+                  "value": "Interpolation",
+                  "description": "The geocode point was matched to a point on a road using interpolation."
                 },
                 {
-                  "value": "InterpolationOffset"
+                  "value": "InterpolationOffset",
+                  "description": "The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street."
                 },
                 {
-                  "value": "Parcel"
+                  "value": "Parcel",
+                  "description": "The geocode point was matched to the center of a parcel."
                 },
                 {
-                  "value": "Rooftop"
+                  "value": "Rooftop",
+                  "description": "The geocode point was matched to the rooftop of a building."
                 }
               ]
             }
@@ -869,7 +873,7 @@
       }
     },
     "Confidence": {
-      "description": "The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. The following description provides more information about how confidence scores are assigned and how results are ranked.\n\nIf the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change appropriately. For example, a location query for \"Paris\" returns \"Paris, France\" and \"Paris, TX\" both with `High` confidence. \"Paris, France\" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area.\n\nIn some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may return \"148th Ave SE\" and \"148th Ave NE\" both with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned.",
+      "description": "The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified.",
       "type": "string",
       "enum": [
         "High",
@@ -881,10 +885,12 @@
         "modelAsString": true,
         "values": [
           {
-            "value": "High"
+            "value": "High",
+            "description": "If the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change appropriately. For example, a location query for \"Paris\" returns \"Paris, France\" and \"Paris, TX\" both with `High` confidence. \"Paris, France\" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area."
           },
           {
-            "value": "Medium"
+            "value": "Medium",
+            "description": "In some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may return \"148th Ave SE\" and \"148th Ave NE\" both with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned."
           },
           {
             "value": "Low"
diff --git a/specification/maps/data-plane/Search/preview/2022-12-01-preview/search.json b/specification/maps/data-plane/Search/preview/2022-12-01-preview/search.json
@@ -670,7 +670,7 @@
             "$ref": "../../../Common/preview/2022-09-01-preview/common.json#/definitions/GeoJsonPoint"
           },
           "calculationMethod": {
-            "description": "The method that was used to compute the geocode point.\n- `Interpolation`: The geocode point was matched to a point on a road using interpolation.\n- `InterpolationOffset`: The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street.\n- `Parcel`: The geocode point was matched to the center of a parcel.\n- `Rooftop`: The geocode point was matched to the rooftop of a building.",
+            "description": "The method that was used to compute the geocode point.",
             "type": "string",
             "enum": [
               "Interpolation",
@@ -683,16 +683,20 @@
               "modelAsString": true,
               "values": [
                 {
-                  "value": "Interpolation"
+                  "value": "Interpolation",
+                  "description": "The geocode point was matched to a point on a road using interpolation."
                 },
                 {
-                  "value": "InterpolationOffset"
+                  "value": "InterpolationOffset",
+                  "description": "The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street."
                 },
                 {
-                  "value": "Parcel"
+                  "value": "Parcel",
+                  "description": "The geocode point was matched to the center of a parcel."
                 },
                 {
-                  "value": "Rooftop"
+                  "value": "Rooftop",
+                  "description": "The geocode point was matched to the rooftop of a building."
                 }
               ]
             }
@@ -1149,7 +1153,7 @@
       }
     },
     "Confidence": {
-      "description": "The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. The following description provides more information about how confidence scores are assigned and how results are ranked.\n\nIf the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change appropriately. For example, a location query for \"Paris\" returns \"Paris, France\" and \"Paris, TX\" both with `High` confidence. \"Paris, France\" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area.\n\nIn some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may return \"148th Ave SE\" and \"148th Ave NE\" both with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned.",
+      "description": "The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified.",
       "type": "string",
       "enum": [
         "High",
@@ -1161,10 +1165,12 @@
         "modelAsString": true,
         "values": [
           {
-            "value": "High"
+            "value": "High",
+            "description": "If the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change appropriately. For example, a location query for \"Paris\" returns \"Paris, France\" and \"Paris, TX\" both with `High` confidence. \"Paris, France\" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area."
           },
           {
-            "value": "Medium"
+            "value": "Medium",
+            "description": "In some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may return \"148th Ave SE\" and \"148th Ave NE\" both with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned."
           },
           {
             "value": "Low"

Original file line number	Diff line number	Diff line change
`@@ -670,7 +670,7 @@`
`670`	`670`	`"$ref": "../../../Common/preview/2022-09-01-preview/common.json#/definitions/GeoJsonPoint"`
`671`	`671`	`},`
`672`	`672`	`"calculationMethod": {`
`673`		- "description": "The method that was used to compute the geocode point.\n- `Interpolation`: The geocode point was matched to a point on a road using interpolation.\n- `InterpolationOffset`: The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street.\n- `Parcel`: The geocode point was matched to the center of a parcel.\n- `Rooftop`: The geocode point was matched to the rooftop of a building.",
	`673`	`+ "description": "The method that was used to compute the geocode point.",`
`674`	`674`	`"type": "string",`
`675`	`675`	`"enum": [`
`676`	`676`	`"Interpolation",`
`@@ -683,16 +683,20 @@`
`683`	`683`	`"modelAsString": true,`
`684`	`684`	`"values": [`
`685`	`685`	`{`
`686`		`- "value": "Interpolation"`
	`686`	`+ "value": "Interpolation",`
	`687`	`+ "description": "The geocode point was matched to a point on a road using interpolation."`
`687`	`688`	`},`
`688`	`689`	`{`
`689`		`- "value": "InterpolationOffset"`
	`690`	`+ "value": "InterpolationOffset",`
	`691`	`+ "description": "The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street."`
`690`	`692`	`},`
`691`	`693`	`{`
`692`		`- "value": "Parcel"`
	`694`	`+ "value": "Parcel",`
	`695`	`+ "description": "The geocode point was matched to the center of a parcel."`
`693`	`696`	`},`
`694`	`697`	`{`
`695`		`- "value": "Rooftop"`
	`698`	`+ "value": "Rooftop",`
	`699`	`+ "description": "The geocode point was matched to the rooftop of a building."`
`696`	`700`	`}`
`697`	`701`	`]`
`698`	`702`	`}`
`@@ -1149,7 +1153,7 @@`
`1149`	`1153`	`}`
`1150`	`1154`	`},`
`1151`	`1155`	`"Confidence": {`
`1152`		- "description": "The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. The following description provides more information about how confidence scores are assigned and how results are ranked.\n\nIf the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change appropriately. For example, a location query for \"Paris\" returns \"Paris, France\" and \"Paris, TX\" both with `High` confidence. \"Paris, France\" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area.\n\nIn some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may return \"148th Ave SE\" and \"148th Ave NE\" both with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned.",
	`1156`	`+ "description": "The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified.",`
`1153`	`1157`	`"type": "string",`
`1154`	`1158`	`"enum": [`
`1155`	`1159`	`"High",`
`@@ -1161,10 +1165,12 @@`
`1161`	`1165`	`"modelAsString": true,`
`1162`	`1166`	`"values": [`
`1163`	`1167`	`{`
`1164`		`- "value": "High"`
	`1168`	`+ "value": "High",`
	`1169`	+ "description": "If the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change appropriately. For example, a location query for \"Paris\" returns \"Paris, France\" and \"Paris, TX\" both with `High` confidence. \"Paris, France\" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area."
`1165`	`1170`	`},`
`1166`	`1171`	`{`
`1167`		`- "value": "Medium"`
	`1172`	`+ "value": "Medium",`
	`1173`	+ "description": "In some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may return \"148th Ave SE\" and \"148th Ave NE\" both with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned."
`1168`	`1174`	`},`
`1169`	`1175`	`{`
`1170`	`1176`	`"value": "Low"`