"}],"short_description":"A guide to integrating RESTful services with the ArcGIS Native Maps SDKs using HTTPS requests","flexible_content":[{"acf_fc_layout":"content","content":"This blog demonstrates how to integrate RESTful services, such as the Places Service, with the Native Maps SDKs by making HTTPS requests using native development frameworks.<\/em><\/strong><\/p>\n The places service<\/a> has recently been added to the rich set of ArcGIS location services for Developers. This new service facilitates a better awareness of location in a given area by letting you search for places, or points of interest. While there is a plan to build an API for the places service in a future version of the ArcGIS Maps SDKs for Native Apps<\/a> (Native Maps SDKs), the service follows a REST architectural style and can therefore be integrated with Native Maps SDKs apps today by making HTTPS requests directly.<\/p>\n To improve my understanding of how the places service could be integrated with the Native Maps SDKs, I decided to expand the spatial awareness capabilities of an internal test app built using the ArcGIS Maps SDK for .NET (.NET Maps SDK). To do this, I implemented the logic for constructing URLs and making HTTPS requests to the places service. The result was significant improvements to the spatial awareness capabilities of the app. To help other Native SDK users add these capabilities to their apps, I have summarized the key learnings from this process.<\/p>\n In this blog, I will:<\/p>\n Where applicable, I\u2019ve provided C# code snippets to help support the descriptions in the text. You can also see the places service being used in an ArcGIS Maps SDK for Java desktop application on my colleague\u2019s GitHub repository<\/a>.<\/p>\n Before we jump into the technical details, let’s first take a look at the terminology I’ll be using throughout this blog, place<\/em> and places service<\/em>.<\/p>\n A place<\/em>, also known as a point of interest<\/em>, is a geographical location that is relevant to a user’s current interest or requirements. The relevance of a given place is dependent on the time, context, and user requirements. For example, the location of a bar is likely to be relevant later in the day (time<\/em>) for someone who is not working (context<\/em>) and is looking for a place to socialize (user requirements<\/em>).<\/p>\n The places service<\/a> is a vast collection of global spatial data (over 50 million places and growing) that can be queried in order to identify places in a given area. The data includes detailed information about each place, such as street address, website, opening hours, and user rating. Data are categorized using over 1000 categories<\/a>, including restaurants, stores, parks, parking, and zoos. As such, queries can be made using a combination of a search string and category ID, and can therefore be as vague (e.g., food<\/em>) or as detailed (e.g., Bonnie Burrito<\/em> in the Burrito Restaurant<\/em> category) as required.<\/p>\n The service is managed and curated by Esri and follows a REST architectural style (a.k.a. RESTful), so is simple and easy to use. Requests are made using HTTPS calls to the open-api spec compliant REST API<\/a>. Each request must be authenticated, either using an API key or an ArcGIS Identity, and is charged in accordance with the ArcGIS location services pricing structure<\/a>, which includes a free tier.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":2102952,"id":2102952,"title":"ExampleOfPlacesSearch","filename":"ExampleOfPlacesSearch.gif","filesize":6006082,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/sdk-net\/developers\/integrate-restful-services-with-the-native-maps-sdks\/exampleofplacessearch","alt":"","author":"346302","description":"","caption":"A search for restaurants in Leith (Edinburgh) using the places service. Places are displayed on the map. Additional information (e.g. address, contact information, and opening hours) is displayed in a callout when a place is clicked. The GIF shows an Esri-internal test app that was created using the .NET Maps SDK.","name":"exampleofplacessearch","status":"inherit","uploaded_to":2102902,"date":"2023-10-17 10:27:56","modified":"2023-10-17 10:30:59","menu_order":0,"mime_type":"image\/gif","type":"image","subtype":"gif","icon":"https:\/\/www.esri.com\/arcgis-blog\/wp-includes\/images\/media\/default.png","width":980,"height":720,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch-213x200.gif","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","medium-width":355,"medium-height":261,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","medium_large-width":768,"medium_large-height":564,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","large-width":980,"large-height":720,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","1536x1536-width":980,"1536x1536-height":720,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","2048x2048-width":980,"2048x2048-height":720,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch-633x465.gif","card_image-width":633,"card_image-height":465,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2023\/10\/ExampleOfPlacesSearch.gif","wide_image-width":980,"wide_image-height":720}},"image_position":"center","orientation":"horizontal","hyperlink":""},{"acf_fc_layout":"content","content":" Now we\u2019ve established the definitions of a place and the places service, we can dive into the practicalities of using the service with the Native Maps SDKs!<\/p>\n Before starting to use the places service, I needed to setup the following:<\/p>\n With a developer account and an authentication method setup, I started to learn how to make HTTPS request to the RESTful places service. I\u2019ve provided a high-level overview of the process below:<\/p>\n I\u2019ll discuss each of these steps in more detail in the next sections.<\/p>\n Calls to the places service are made by sending HTTPS requests. Each URL used to make a call to the places service requires the following elements:<\/p>\n I\u2019ve written an example of manually constructing a URL from each of the elements outlined above in the C# snippet below (all code snippets in this blog are in C# and can be used with the .NET Maps SDK. However, similar workflows can be followed for other Native Maps SDKs products<\/em>).<\/p>\n This request is a \u201cnearby\u201d search, meaning we are requesting places within a certain radius of a given location (note: the radius parameter is optional and has a default value of 1000m). The key-value pairs (identified by &<\/em><\/strong> character) in the parameter list (starts after the ?<\/em><\/strong> character), describe a request for any place associated with the word \u201cbakery\u201d and within 100m of the location with a latitude of 55.94417 and a longitude of -3.19551 (Esri’s Edinburgh R&D Office). The results are to be returned in pretty JSON format (f=pjson<\/em><\/strong>) and the request should be authenticated using the specified token. A request such as this helps us developers find the location of the nearest cruffin!<\/p>\n There are more examples of requests being made to the places service on the esridevs Postman places service page<\/a>.<\/p>\n Many development frameworks provide helper classes, or there are freely available libraries that can be used to make HTTPS requests with a given URL. In this blog, I\u2019ve assumed you have access to relevant helper classes or a suitable library. To help you identify these, here\u2019s a few suggestions for some of the Native SDK development frameworks (Java, Swift, Qt, and .NET):<\/p>\n There\u2019s also an example of making an HTTPS request using the HttpClient<\/em><\/strong>, UriBuilder<\/em><\/strong>, HttpUtility<\/em><\/strong>, and HttpResponseMessage<\/em><\/strong> helper classes from the .NET framework in the code snippet below.<\/p>\n So, we now know how to send an HTTPS request to the RESTful places service! Next, we\u2019ll look at the response from the service and understand how we can process it.<\/p>\n Requests made to the places service return information in JSON format (or Pretty JSON format). The example request shown above returns the following response:<\/p>\n In the example shown above, the response comprises an array called results<\/strong> that contains places meeting the search criteria. In this case, the array contains one place. Each place has a placeId<\/strong>, location<\/strong>, array of categories<\/strong> (a place can be associated with multiple categories), and a name<\/strong>. Additionally, because the type of the request is near-point<\/em>, each result has a distance<\/strong> attribute.<\/p>\n You can find more detailed information about the content of the response for each request type in the places service documentation (e.g. near-point Response details<\/a>).<\/p>\n With the json response from the places service, we now need to parse the information. Many development frameworks include a JSON deserializer which can be used to convert a JSON string into user-defined objects, for example:<\/p>\n To deserialize the response, I needed to define some custom C# classes, which I\u2019ve shown in the snippet below. Note:<\/strong> These are objects that were created for the purposes of this blog and are not included with the Native Maps SDKs.<\/p>\nIntroduction<\/strong><\/h2>\n
\n
What is a place?<\/strong><\/h2>\n
What is the places service?<\/strong><\/h2>\n
Prerequisites?<\/strong><\/h2>\n
\n
\n
\n
Overview of process for making a request<\/strong><\/h2>\n
\n
\n
Creating a URL<\/strong><\/h2>\n
\n
\n
\n
string<\/span> _scheme = \"https:\/\/\"<\/span>;\r\nstring<\/span> _domainName = \"places-api.arcgis.com\/\"<\/span>;\r\nstring<\/span> _path = \"arcgis\/rest\/services\/places-service\/v1\/\"<\/span>;\r\nstring<\/span> _requestType = \"places\/near-point\"<\/span>;\r\nstring<\/span> _parameterList = \"?searchText=bakery&x=-3.19551&y=55.94417&radius=100&f=pjson&token=<ACCESS_TOKEN>\"<\/span>;\r\n\r\nConsole.WriteLine(_scheme + _domainName + _path + _requestType + _parameterList);\r\n\r\n\/\/ Prints: https:\/\/places-api.arcgis.com\/arcgis\/rest\/services\/places-service\/v1\/places\/near-point?searchText=bakery&x=-3.19551&y=55.94417&radius=100&f=pjson&token=<ACCESS_TOKEN><\/span>\r\n<\/pre>\n<\/div>\nNote:<\/span> copying the URL in the snippet above into a browser will enable you to make a request and see the response. To do this, you will need to replace the <ACCESS_TOKEN><\/span> statement with a valid token.\r\n<\/pre>\n<\/div>\nSending a request<\/strong><\/h2>\n
\n\n
\n Development Framework<\/strong><\/th>\n Helper classes\/libraries<\/strong><\/th>\n<\/tr>\n \n .NET<\/td>\n HttpClient<\/em><\/strong>, UriBuilder<\/em><\/strong>, and HttpUtility<\/em><\/strong><\/td>\n<\/tr>\n \n Qt<\/td>\n QNetworkRequest<\/em><\/strong>, QUrl<\/em><\/strong>, and QUrlQuery<\/em><\/strong><\/td>\n<\/tr>\n \n Swift<\/td>\n URLSession<\/em><\/strong> and swift-http-types<\/em><\/strong> library<\/td>\n<\/tr>\n \n Java<\/td>\n HttpClient<\/em><\/strong>, HttpRequest<\/em><\/strong>, URI<\/em><\/strong>, and HttpURLConnection<\/em><\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n async<\/span> Task<string<\/span>> MakeRequest()\r\n{\r\n HttpClient _httpClient = new<\/span>(); \/\/ Instantiate one HttpClient in an application.<\/span>\r\n string<\/span> _response = \"\"<\/span>;\r\n\r\n try<\/span>\r\n {\r\n System.Net.Http.HttpResponseMessage _httpResponse = await<\/span> _httpClient.GetAsync(ConstructURLUsingBuilder());\r\n if<\/span> (!_httpResponse.IsSuccessStatusCode)\r\n throw<\/span> new<\/span> Exception<\/span>(\"Response status code: \"<\/span> + _httpResponse.StatusCode);\r\n _response = await<\/span> _httpResponse.Content.ReadAsStringAsync();\r\n }\r\n catch<\/span> (HttpRequestException e)\r\n {\r\n Console.WriteLine(\"Message: {0} \"<\/span>, e.Message);\r\n }\r\n return<\/span> _response;\r\n}\r\n\r\nUri ConstructURLUsingBuilder<\/span>()\r\n{\r\n UriBuilder _uriBuilder = new<\/span>(\"places-api.arcgis.com\"<\/span>);\r\n\r\n string<\/span> _path = \"\/arcgis\/rest\/services\/places-service\/v1\/\"<\/span>;\r\n string<\/span> _requestType = \"places\/near-point\"<\/span>;\r\n\r\n _uriBuilder.Path = _path + _requestType;\r\n\r\n NameValueCollection _urlParameters = HttpUtili-ty.ParseQueryString(_uriBuilder.Query);\r\n\r\n _urlParameters[\"searchText\"<\/span>] = \"bakery\"<\/span>;\r\n _urlParameters[\"x\"<\/span>] = \"-3.19551\"<\/span>;\r\n _urlParameters[\"y\"<\/span>] = \"55.94417\"<\/span>;\r\n _urlParameters[\"radius\"<\/span>] = \"100\"<\/span>;\r\n _urlParameters[\"f\"<\/span>] = \"pjson\"<\/span>;\r\n _urlParameters[\"token\"<\/span>] = \"<ACCESS_TOKEN>\"<\/span>;\r\n\r\n _uriBuilder.Query = _urlParameters.ToString();\r\n\r\n return<\/span> _uriBuilder.Uri;\r\n}\r\n<\/pre>\n<\/div>\nProcess the response<\/strong><\/h2>\n
Response format<\/em><\/strong><\/h5>\n
{\r\n \"results\"<\/span>: [\r\n {\r\n \"placeId\"<\/span>: \"b36eaff62de292c31c99a7ed4e47c2d2\"<\/span>,\r\n \"location\"<\/span>: {\r\n \"x\"<\/span>: -3.194024<\/span>,\r\n \"y\"<\/span>: 55.943964<\/span>\r\n },\r\n \"categories\"<\/span>: [\r\n {\r\n \"categoryId\"<\/span>: \"13002\"<\/span>,\r\n \"label\"<\/span>: \"Bakery\"<\/span>\r\n },\r\n {\r\n \"categoryId\"<\/span>: \"13065\"<\/span>,\r\n \"label\"<\/span>: \"Restaurant\"<\/span>\r\n }\r\n ],\r\n \"name\"<\/span>: \"Soderberg Pavillon\"<\/span>,\r\n \"distance\"<\/span>: 95.3<\/span>\r\n }\r\n ]\r\n}\r\n<\/pre>\n<\/div>\nDeserialization<\/em><\/strong><\/h5>\n
PlaceResult? placeResult = JsonConvert.DeserializeObject<PlaceResult>(searchResult);\r\n<\/pre>\n<\/div>\n