Find places

Before starting this tutorial:

1. You need an ArcGIS Location Platform or ArcGIS Online account.

2. Your system meets the system requirements.

Option 1: Develop the code

To start the tutorial, complete the Display a map tutorial. This creates a map to display the Santa Monica Mountains in California using the topographic basemap from the ArcGIS Basemap Styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more .

Continue with the following instructions search for places of interest, such as hotels, cafes, and gas stations using the ArcGIS Geocoding service A geocoding service is a service that can search for addresses, place addresses, businesses, reverse geocode coordinates to addresses, provide suggestions for places, and perform bulk geocoding. It is hosted by Esri as the ArcGIS Geocoding service and can also be hosted in ArcGIS Enterprise. Learn more . First, you need to set the develop credentials in your app so that you can access the ArcGIS Geocoding service A geocoding service is a service that can search for addresses, place addresses, businesses, reverse geocode coordinates to addresses, provide suggestions for places, and perform bulk geocoding. It is hosted by Esri as the ArcGIS Geocoding service and can also be hosted in ArcGIS Enterprise. Learn more .

Set developer credentials

If you implemented API key authentication API key authentication is a type of authentication that uses an API key to authenticate requests to ArcGIS services and secure portal items. Learn more in the Display a map tutorial, the API key access token will only have the Basemaps privilege. The Find places tutorial requires the Geocoding privilege to find places using the LocatorTask. To create an API Key access token that has the Basemaps and Geocoding privileges, see the Set up authentication step and then follow the instructions below.

Update the map

1. In Xcode, in the Project Navigator, click ContentView.swift.

2. Create a private extension of ContentView and make a private class named Model of type ObservableObject. Add a @StateObject variable of the Model to the ContentView. See the programming patterns page for more information on how to manage states.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var map = {
   6
           let map = Map(basemapStyle: .arcGISTopographic)
   7
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   8
           return map
   9
       }()
   10
   
   11
   }
   12
   
   13
   private extension ContentView {
   14
   
   15
       private class Model: ObservableObject {
   16
   
   17
       }
   18
   
   19
   }

3. Create a GraphicsOverlay named graphicsOverlay in the Model class. A graphics overlay A graphics overlay is a client-side, temporary container of graphics to display on a map view or scene view. Learn more is a container for graphics A graphic is a visual element composed of a geometry, symbol, and attributes that is displayed on a map or scene. Learn more .

   More info

   A graphics overlay A graphics overlay is a client-side, temporary container of graphics to display on a map view or scene view. Learn more is a container for graphics A graphic is a visual element composed of a geometry, symbol, and attributes that is displayed on a map or scene. Learn more . It is used with a map view A map view is a user interface that displays map layers and graphics in 2D. It controls the area (extent) of the map that is visible and supports user interactions such as pan and zoom. Learn more to display graphics on a map A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more . You can add more than one graphics overlay to a map view. Graphics overlays are displayed on top of all the other layers A layer is a reference to a collection of geographic data that is used to access and display data. The data for layers are typically provided by the basemap layer service and data services. Learn more .

   ContentView.swift

   1
       private class Model: ObservableObject {
   2
   
   3
           let graphicsOverlay = GraphicsOverlay()
   4
   
   5
       }

4. Add the graphics overlay to the map view, wrap the map view inside a MapViewReader, and expose the MapViewProxy class in its closure. MapViewProxy provides operations that can be performed on the map view, such as ‘identify’. For more information see Perform GeoView operations.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapViewReader { mapViewProxy in
   4
   
   5
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   6
   
   7
           }
   8
   
   9
       }

Set up the LocatorTask

A locator task is used to search for places using a geocoding service. Results from this search contain the place location and additional information ( attributes Attributes are fields and values for a single feature or non-spatial record. They are typically stored in a database or service such as a feature service. Learn more ). Create the locator task along with any variables and methods needed to perform the search and display the results.

1. In the Model, create a LocatorTask property named locator based on the Geocoding service.

   More info

   A locator task is used to convert an address to a point A point is a type of geometry containing a single set of x,y coordinates and a spatial reference. Learn more (geocode) or vice-versa ( reverse geocode Reverse geocoding is the process of converting a point to its nearest address or place. Learn more ). An address includes any type of information that distinguishes a place. A locator A locator is an ArcGIS dataset that stores address information and the rules for translating descriptions of places (such as street addresses or place names) into spatial data that can be displayed on a map. Learn more involves finding matching locations for a given address. Reverse-geocoding is the opposite and finds the closest address for a given point.

   ContentView.swift

   1
   private extension ContentView {
   2
   
   3
       private class Model: ObservableObject {
   4
   
   5
           let graphicsOverlay = GraphicsOverlay()
   6
   
   7
           let locator = LocatorTask(
   8
               url: URL(string: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer")!
   9
           )
   10
   
   11
       }
   12
   
   13
   }

2. To support the geocode operation, create an enum named Category in the ContentView extension. Provide a String named “label” and a UIColor named “color”. Each category is searched using its label and is distinguished on the map using its associated color.

   More info

   This tutorial uses category filtering to provide accurate search results based on pre-determined place categories. Feel free to modify this list to your specific requirements.

   ContentView.swift

   1
   private extension ContentView {
   2
   
   3
       enum Category: CaseIterable, Equatable {
   4
           case coffeeShop, gasStation, food, hotel, parksOutdoors
   5
   
   6
           var label: String {
   7
               switch self {
   8
               case .coffeeShop: return "Coffee shop"
   9
               case .gasStation: return "Gas station"
   10
               case .food: return "Food"
   11
               case .hotel: return "Hotel"
   12
               case .parksOutdoors: return "Parks and Outdoors"
   13
               }
   14
           }
   15
   
   16
           var color: UIColor {
   17
               switch self {
   18
               case .coffeeShop: return .brown
   19
               case .gasStation: return .orange
   20
               case .food: return .purple
   21
               case .hotel: return .blue
   22
               case .parksOutdoors: return .green
   23
               }
   24
           }
   25
       }
   26
   
   27
       private class Model: ObservableObject {
   28
   
   29
           let graphicsOverlay = GraphicsOverlay()
   30
   
   31
           let locator = LocatorTask(
   32
               url: URL(string: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer")!
   33
           )
   34
   
   35
       }
   36
   
   37
   }

3. In the ContentView struct, create a private variable named geoViewExtent of type Envelope with the @State property wrapper. This will be used to define the search location.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var geoViewExtent: Envelope?
   6
   
   7
       @State private var map = {
   8
           let map = Map(basemapStyle: .arcGISTopographic)
   9
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   10
           return map
   11
       }()
   12
   
   13
       var body: some View {
   14
   
   15
           MapViewReader { mapViewProxy in
   16
   
   17
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   18
   
   19
           }
   20
   
   21
       }
   22
   
   23
   }

4. In the body, add the onVisibleAreaChanged(perform:) method to the map view. Set the geoViewExtent variable to the new visible area’s extent.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapViewReader { mapViewProxy in
   4
   
   5
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   6
   
   7
                   .onVisibleAreaChanged { newVisibleArea in
   8
                       geoViewExtent = newVisibleArea.extent
   9
                   }
   10
   
   11
           }
   12
   
   13
       }

5. In the Model, create a private, asynchronous method called findPlaces(forCategory:searchPoint:) to perform the geocode Geocoding is the process of converting text for an address or place to a complete address with a location. Learn more search operation. The method takes a parameter of type Category that you created in the previous step to indicate which category of places to search for and a Point that acts as the preferred search location.

   ContentView.swift

   1
       private class Model: ObservableObject {
   2
   
   3
           let graphicsOverlay = GraphicsOverlay()
   4
   
   5
           let locator = LocatorTask(
   6
               url: URL(string: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer")!
   7
           )
   8
   
   9
           func findPlaces(forCategory category: Category, searchPoint: Point? = nil) async {
   10
   
   11
           }
   12
   
   13
       }

6. Clear the previous results by removing all graphics from the graphics overlay. Create and configure new GeocodeParameters. Populate them with the searchPoint parameter as the search location and add result attribute names.

   ContentView.swift

   1
           func findPlaces(forCategory category: Category, searchPoint: Point? = nil) async {
   2
   
   3
               graphicsOverlay.removeAllGraphics()
   4
               let geocodeParameters = GeocodeParameters()
   5
               geocodeParameters.preferredSearchLocation = searchPoint
   6
               geocodeParameters.addResultAttributeNames(["Place_addr", "PlaceName"])
   7
   
   8
           }

7. Perform the search query using geocode(forSearchText:using:). Pass in the category’s label and the geocode parameters.

   ContentView.swift

   1
           func findPlaces(forCategory category: Category, searchPoint: Point? = nil) async {
   2
   
   3
               graphicsOverlay.removeAllGraphics()
   4
               let geocodeParameters = GeocodeParameters()
   5
               geocodeParameters.preferredSearchLocation = searchPoint
   6
               geocodeParameters.addResultAttributeNames(["Place_addr", "PlaceName"])
   7
   
   8
               do {
   9
                   let geocodeResults = try await locator.geocode(forSearchText: category.label, using: geocodeParameters)
   10
   
   11
               } catch {
   12
                   print(error)
   13
               }
   14
   
   15
           }

8. Create graphics for each of the results and add them to the graphics overlay.

   More info

   Populate the graphicsOverlay with SimpleMarkerSymbols representing each place returned in the search results. This is very similar to the Add a point, line, and polygon tutorial.

   ContentView.swift

   1
           func findPlaces(forCategory category: Category, searchPoint: Point? = nil) async {
   2
   
   3
               graphicsOverlay.removeAllGraphics()
   4
               let geocodeParameters = GeocodeParameters()
   5
               geocodeParameters.preferredSearchLocation = searchPoint
   6
               geocodeParameters.addResultAttributeNames(["Place_addr", "PlaceName"])
   7
   
   8
               do {
   9
                   let geocodeResults = try await locator.geocode(forSearchText: category.label, using: geocodeParameters)
   10
   
   11
                   if !geocodeResults.isEmpty {
   12
                       let placeSymbol = SimpleMarkerSymbol(
   13
                           style: .circle,
   14
                           color: category.color,
   15
                           size: 10
   16
                       )
   17
                       placeSymbol.outline = SimpleLineSymbol(
   18
                           style: .solid,
   19
                           color: .white,
   20
                           width: 2
   21
                       )
   22
                       let graphics = geocodeResults.map { Graphic(geometry: $0.displayLocation, attributes: $0.attributes, symbol: placeSymbol) }
   23
                       graphicsOverlay.addGraphics(graphics)
   24
                   }
   25
   
   26
               } catch {
   27
                   print(error)
   28
               }
   29
   
   30
           }

Add a category picker

You will add a Picker to the user interface to show categories of places to find, for example, coffee shops or gas stations. Each category will be displayed with a different color on the map.

1. In the ContentView struct, add a variable of type Category with the @State property wrapper and give it a default value of coffeeShop. This will indicate the currently selected category.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var geoViewExtent: Envelope?
   6
   
   7
       @State private var selectedCategory: Category = .coffeeShop
   8
   
   9
       @State private var map = {
   10
           let map = Map(basemapStyle: .arcGISTopographic)
   11
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   12
           return map
   13
       }()

2. In the ContentView body, add a toolbar view modifier to the map view that places a Toolbar at the bottom of the view where the Picker will be contained.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapViewReader { mapViewProxy in
   4
   
   5
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   6
   
   7
                   .onVisibleAreaChanged { newVisibleArea in
   8
                       geoViewExtent = newVisibleArea.extent
   9
                   }
   10
   
   11
                   .toolbar {
   12
                       ToolbarItemGroup(placement: .bottomBar) {
   13
   
   14
                       }
   15
                   }
   16
   
   17
           }
   18
   
   19
       }

3. Add a Picker to the toolbar and label it “Choose a category”. Set the selection to $selectedCategory. This will iterate through .allCases of Category to populate the Picker with all the category labels. Add the .labelsHidden modifier.

   ContentView.swift

   1
                   .toolbar {
   2
                       ToolbarItemGroup(placement: .bottomBar) {
   3
   
   4
                           Picker("Choose a category", selection: $selectedCategory) {
   5
                               ForEach(Category.allCases, id: \.self) { category in
   6
                                   Text(category.label)
   7
                               }
   8
                           }
   9
                           .labelsHidden()
   10
   
   11
                       }
   12
                   }

4. Lastly, add a .task modifier to the Picker that calls the model’s findPlaces(forCategory:searchPoint:) function. Pass in selectedCategory and the geoViewExtent?.center. This will initiate a geocode search when a category is selected.

   ContentView.swift

   1
                   .toolbar {
   2
                       ToolbarItemGroup(placement: .bottomBar) {
   3
   
   4
                           Picker("Choose a category", selection: $selectedCategory) {
   5
                               ForEach(Category.allCases, id: \.self) { category in
   6
                                   Text(category.label)
   7
                               }
   8
                           }
   9
                           .labelsHidden()
   10
   
   11
                           .task(id: selectedCategory) {
   12
                               await model.findPlaces(forCategory: selectedCategory, searchPoint: geoViewExtent?.center)
   13
                           }
   14
   
   15
                       }
   16
                   }

Show information about a tapped location in the map

An identify Identify is a query based on a point on a map or scene that is used to find feature, graphic, or raster cell data. Learn more operation can be used to get information about a geoelement A geoelement refers to any geographic element in a map or map view that can be identified by its location to return attribute information. Learn more (such as a graphic A graphic is a visual element composed of a geometry, symbol, and attributes that is displayed on a map or scene. Learn more ) at a location where the user has tapped on the map. A callout A callout is a container view that can be added over the map and anchored to a coordinate with a leader. Learn more can be used to display this information.

1. In the ContentView struct, add objects to track the map and screen locations. Create Point and CGPoint variables with the @State property wrappers. Name them mapLocation and tapLocation, respectively.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var geoViewExtent: Envelope?
   6
   
   7
       @State private var selectedCategory: Category = .coffeeShop
   8
   
   9
       @State private var tapLocation: CGPoint?
   10
       @State private var mapLocation: Point?
   11
   
   12
       @State private var map = {
   13
           let map = Map(basemapStyle: .arcGISTopographic)
   14
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   15
           return map
   16
       }()

2. Add objects to support the callout. Create CalloutPlacement and String variables with the @State property wrapper. Name them calloutPlacement and calloutText respectively.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var geoViewExtent: Envelope?
   6
   
   7
       @State private var selectedCategory: Category = .coffeeShop
   8
   
   9
       @State private var tapLocation: CGPoint?
   10
       @State private var mapLocation: Point?
   11
   
   12
       @State private var calloutPlacement: CalloutPlacement?
   13
       @State private var calloutText: String?
   14
   
   15
       @State private var map = {
   16
           let map = Map(basemapStyle: .arcGISTopographic)
   17
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   18
           return map
   19
       }()

3. In the body, add a .callout modifier to the map view. Pass in $calloutPlacement as the placement parameter. In the closure, create a Text object using the calloutText and provide a default String in case it is nil.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapViewReader { mapViewProxy in
   4
   
   5
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   6
   
   7
                   .callout(placement: $calloutPlacement.animation(.default.speed(2))) { _ in
   8
                       Text(calloutText ?? "No address found.")
   9
                           .font(.callout)
   10
                           .padding(8)
   11
                           .frame(maxWidth: 350)
   12
                   }
   13
   
   14
                   .onVisibleAreaChanged { newVisibleArea in
   15
                       geoViewExtent = newVisibleArea.extent
   16
                   }
   17
   
   18
                   .toolbar {
   19
                       ToolbarItemGroup(placement: .bottomBar) {
   20
   
   21
                           Picker("Choose a category", selection: $selectedCategory) {
   22
                               ForEach(Category.allCases, id: \.self) { category in
   23
                                   Text(category.label)
   24
                               }
   25
                           }
   26
                           .labelsHidden()
   27
   
   28
                           .task(id: selectedCategory) {
   29
                               await model.findPlaces(forCategory: selectedCategory, searchPoint: geoViewExtent?.center)
   30
                           }
   31
   
   32
                       }
   33
                   }
   34
   
   35
           }
   36
   
   37
       }

4. Add the onSingleTapGesture(perform:) method to the map view and set mapLocation and tapLocation.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapViewReader { mapViewProxy in
   4
   
   5
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   6
   
   7
                   .callout(placement: $calloutPlacement.animation(.default.speed(2))) { _ in
   8
                       Text(calloutText ?? "No address found.")
   9
                           .font(.callout)
   10
                           .padding(8)
   11
                           .frame(maxWidth: 350)
   12
                   }
   13
   
   14
                   .onVisibleAreaChanged { newVisibleArea in
   15
                       geoViewExtent = newVisibleArea.extent
   16
                   }
   17
   
   18
                   .onSingleTapGesture { screenPoint, mapPoint in
   19
                       tapLocation = screenPoint
   20
                       mapLocation = mapPoint
   21
                   }
   22
   
   23
                   .toolbar {
   24
                       ToolbarItemGroup(placement: .bottomBar) {
   25
   
   26
                           Picker("Choose a category", selection: $selectedCategory) {
   27
                               ForEach(Category.allCases, id: \.self) { category in
   28
                                   Text(category.label)
   29
                               }
   30
                           }
   31
                           .labelsHidden()
   32
   
   33
                           .task(id: selectedCategory) {
   34
                               await model.findPlaces(forCategory: selectedCategory, searchPoint: geoViewExtent?.center)
   35
                           }
   36
   
   37
                       }
   38
                   }
   39
   
   40
           }
   41
   
   42
       }

5. Add a .task modifier to the map view, passing in tapLocation as the idefntifier. Ensure that the location objects are not nil.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapViewReader { mapViewProxy in
   4
   
   5
               MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   6
   
   7
                   .callout(placement: $calloutPlacement.animation(.default.speed(2))) { _ in
   8
                       Text(calloutText ?? "No address found.")
   9
                           .font(.callout)
   10
                           .padding(8)
   11
                           .frame(maxWidth: 350)
   12
                   }
   13
   
   14
                   .onVisibleAreaChanged { newVisibleArea in
   15
                       geoViewExtent = newVisibleArea.extent
   16
                   }
   17
   
   18
                   .onSingleTapGesture { screenPoint, mapPoint in
   19
                       tapLocation = screenPoint
   20
                       mapLocation = mapPoint
   21
                   }
   22
   
   23
                   .task(id: tapLocation) {
   24
                       guard let tapLocation, let mapLocation else { return }
   25
   
   26
                   }
   27
   
   28
                   .toolbar {
   29
                       ToolbarItemGroup(placement: .bottomBar) {
   30
   
   31
                           Picker("Choose a category", selection: $selectedCategory) {
   32
                               ForEach(Category.allCases, id: \.self) { category in
   33
                                   Text(category.label)
   34
                               }
   35
                           }
   36
                           .labelsHidden()
   37
   
   38
                           .task(id: selectedCategory) {
   39
                               await model.findPlaces(forCategory: selectedCategory, searchPoint: geoViewExtent?.center)
   40
                           }
   41
   
   42
                       }
   43
                   }
   44
   
   45
           }
   46
   
   47
       }

6. Perform identify(on:screenPoint:tolerance:returnPopupsOnly:maximumResults:) on the map view proxy to identify the graphics at the tapLocation.

   ContentView.swift

   1
                   .task(id: tapLocation) {
   2
                       guard let tapLocation, let mapLocation else { return }
   3
   
   4
                       do {
   5
                           let identifyResult = try await mapViewProxy.identify(
   6
                               on: model.graphicsOverlay,
   7
                               screenPoint: tapLocation,
   8
                               tolerance: 12
   9
                           )
   10
   
   11
                       } catch {
   12
                           print(error)
   13
                       }
   14
   
   15
                   }

7. Lastly, assign the calloutText and calloutPlacement variables with with attributes from the first graphic of the identify results. This change in state will trigger the callout to be displayed.

   ContentView.swift

   1
                   .task(id: tapLocation) {
   2
                       guard let tapLocation, let mapLocation else { return }
   3
   
   4
                       do {
   5
                           let identifyResult = try await mapViewProxy.identify(
   6
                               on: model.graphicsOverlay,
   7
                               screenPoint: tapLocation,
   8
                               tolerance: 12
   9
                           )
   10
   
   11
                           if let graphic = identifyResult.graphics.first {
   12
                               let placeName = graphic.attributes["PlaceName"] as? String ?? "Unknown"
   13
                               let placeAddress = graphic.attributes["Place_addr"] as? String ?? "no address provided"
   14
                               calloutText = "\(placeName)\n\(placeAddress)"
   15
                               calloutPlacement = .location(mapLocation)
   16
                           } else {
   17
                               calloutPlacement = nil
   18
                           }
   19
   
   20
                       } catch {
   21
                           print(error)
   22
                       }
   23
   
   24
                   }

Run the solution

Press Command + R to run the app.

When the app opens, use the picker to search different categories of places in the Malibu area near Los Angeles, California. You can tap one of the places and see its name and address.

Option 2: Download the solution

1. Click the Download solution link under Solution and unzip the file to a location on your machine.

2. Open the .xcodeproj file in Xcode.

Since the downloaded solution does not contain authentication credentials, you must add the developer credentials that you created in the Set up authentication section.

Set developer credentials in the solution

To allow your app users to access ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more , use the developer credentials that you created in the Set up authentication step to authenticate requests for resources.

Run the solution

Press Command + R to run the app.

When the app opens, use the picker to search different categories of places in the Malibu area near Los Angeles, California. You can tap one of the places and see its name and address.