Geocode and search

Using a place name or street address as input, you can find locations of interest and interact with them on the map. The process of matching locations on the map to an address is referred to as geocoding. An online or local locator contains the logic for matching addresses, place names, or categories to geographic locations.

What is geocoding?

Geocoding is the process of inputting text for an address or place name to return a geographic location and additional address information (the complete address). For example, you can geocode "1600 Pennsylvania Ave, DC" to return its location (-77.03654 longitude, 38.89767 latitude) and a more complete address ("1600 Pennsylvania Avenue NW, Washington, DC 20500").

You can use geocoding to:

• Find the location of an address or place.
• Convert incomplete address text to a complete address.
• Provide a list of candidates for an incomplete address or place.

Find places

Place search, also known as point of interest (POI) search, uses a name or category to find geographic entities (such as businesses, administrative boundaries, and other features). For example, you can search for restaurants near a location, counties in a state, or land features such as the Grand Canyon.

There are two types of searches you can perform: local and global. A local search uses a location to prioritize results that are nearby or a search extent to confine the search area and restrict results by a defined boundary. A global search is an open search that typically isn't confined to an extent.

You can use place search to:

• Find the locations of places around the world.
• Locate businesses near a location.
• Search for places by category such as restaurants, gas stations, or schools.
• Find and display places on a map.

Suggest

Suggest functionality allows character-by-character autocomplete suggestions to be generated from user input in your geocoding application. This capability facilitates the interactive search experience by reducing the number of characters that need to be entered before a suggested match is obtained.

You can pass most of the same parameters to generate suggestions as you would pass when geocoding, such as preferred search location and category. Once a suitable auto-complete suggestion is returned, the suggest result can be passed directly to the geocoding operation. To optimize quality and performance you should pass the same parameters to suggest and to geocode.

You can use suggest to:

• Generate more complete input when the user is unsure of an exact place name or address.
• Minimize the number of characters a user needs to type to get a good result.
• Optimize quality and performance by passing a suggest result to geocode with the same parameters.

Reverse geocoding

Reverse geocoding is the process of interpolating a street address or identifying a place name for an input point. To refine the search, you can specify a feature type to return a specific type of address such as only POIs or addresses. You can also specify whether to return a street address or rooftop location.

The geocoding service uses the location and all parameters to return a single address, place, or intersection that is the closest match. This reverse geocoding result may contain a number of attributes such as the place name, full address, city, region, and location.

Reverse geocoding will always return the closest result, and the result may be an address, place, or intersection. If the locator you're using was built with only POI data, the result will always be a POI. If your locator was built to support multiple feature types, you can pass a feature type parameter to ensure that the result returned is of the desired type.

You can use reverse geocoding to:

• Get the nearest address, place, or intersection to your current location.
• Show an address or place name when you tap on a map.
• Find the nearest address, place, or intersection for a geographic location.

How geocoding works

Geocoding is implemented using an online or local locator. Specify an address, output data fields, and optionally, additional parameters to refine the search. The more complete you can make the input address (including a postal code, for example), the more likely the locator will find an exact match. To refine the search, you can provide additional parameters such as a search location, category, country code, and other parameters.

The locator parses the address and uses all of the parameters to return a set of address candidates. Each candidate contains a full address, location, attributes, and a score (0-100) that indicates how well it was matched based on the feature type of the locator used to make the match. Candidates are always returned in order from most to least exact irrespective of score; you never need to sort the candidates that are returned. Because score is relative to feature type, a slightly lower score on a PointAddress match will still be a better candidate than a higher score on a postal match, for instance. By default, the matched address, score, and location are returned with the geocode results. To return additional available data fields, set the output fields parameter in the geocode parameters.

For a place search, instead of passing a single-line address value as input, you can provide a place name or category. The geocode parameters allow you to prefer candidates that are closer to a specified location, which can be useful if searching for facilities near the current position. Depending on the data used to build your locator, you can return information about the locations, such as addresses, phone numbers, and URLs for candidates, as well as the distance from a reference location.

You can use geocode parameters to refine or restrict search results when geocoding place names just as you do with an address search.

Locator task

Geocoding, reverse geocoding, or place searches are implemented using a locator task. This task is configured with an online or local locator that contains the logic for matching addresses, place names, or categories to geographic locations.

You create a LocatorTask by passing a URI (for an online locator) or a path (for a local locator). The following example creates a new LocatorTask that uses the Geocoding service.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
    // Supply your access token.
    const QString accessToken = QStringLiteral("YOUR_ACCESS_TOKEN");

    // Create a new locator task from the URL provided.
    LocatorTask* locatorTask = new LocatorTask(QUrl(
        "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"), this);

    // Set the access token on the locator task's API key.
    locatorTask->setApiKey(accessToken);

    // Provide the address text string to geocode.
    const QString searchText = "1600 Pennsylvania Ave NW, DC";

    // Call the geocode async method with the provided search address on the locator task.
    locatorTask->geocodeAsync(searchText).then(this,[](const QList<GeocodeResult>& geocodeResults)
    {
        // Only continue if we have results.
        if (!geocodeResults.isEmpty())
        {
            // Get the first geocode result.
            const GeocodeResult result = geocodeResults.at(0);

            // Display the results.
            qDebug() << "Found" << result.label(); // QString
            qDebug() << "at" << result.displayLocation().toJson(); // Point class
            qDebug() << "with score" << result.score(); // Double
        }

    });

Geocode parameters

When geocoding an address or place, you can optionally provide preferences for the geocoding operation. The following list describes some of the properties you can control:

• Country—The code for the country to which geocoding should be restricted.
• Maximum results—A limit for the maximum number of address candidates to return.
• Output language—The language (culture) in which result attributes will be returned (supported output languages will vary depending on how the locator was built.)
• Output spatial reference—The spatial reference in which geographic locations for address candidates will be returned.
• Result attributes—A list of field names to include in the results (available fields can be queried from the locator.)
• Preferred search location—A geographic point that prioritizes nearby locations as results.

Specify geocoding preferences using a GeocodeParameters object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
    // Define the geocode parameters and set the perferred search location and categories.
    GeocodeParameters parameters;
    parameters.setPreferredSearchLocation(Point(-118.2000, 34.0013, SpatialReference::wgs84()));
    parameters.setCategories({"Mexican Food"});

    // Get the QStringList of result attributes names from the geocode parameters.
    QStringList resultAttributeNames = parameters.resultAttributeNames();

    // Add a "Score" and "Distance" to the QStringList of result attributes names.
    resultAttributeNames.append("Score");
    resultAttributeNames.append("Distance");

Geocode results

Depending on how specific and complete the input address is, you may get several candidates from a geocode operation. Results are ordered by quality of the match and scored based on the quality of the match relative to the feature type of the result. The first candidate should always be considered as the best match. Additional candidate information can be obtained by specifying supplemental output fields to include in the results. For a complete list of fields available for the Geocoding service, see Output fields in the ArcGIS services reference. If you built a custom locator, your locator will contain the output fields that you designated in the locator properties as well as any custom output fields you may have created.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
    // Supply your access token.
    const QString accessToken = QStringLiteral("YOUR_ACCESS_TOKEN");

    // Set the access token on the ArcGIS runtime environment's API key.
    ArcGISRuntimeEnvironment::setApiKey(accessToken);

    // Create a new locator task from the URL provided.
    LocatorTask* task = new LocatorTask(QUrl(
        "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"), this);

    // Or set an access token on the Locator Task:
    // task->setApiKey(accessToken);


    // Define the geocode parameters and set the perferred search location and categories.
    GeocodeParameters parameters;
    parameters.setPreferredSearchLocation(Point(-118.2000, 34.0013, SpatialReference::wgs84()));
    parameters.setCategories({"Mexican Food"});

    // Get the QStringList of result attributes names from the geocode parameters.
    QStringList resultAttributeNames = parameters.resultAttributeNames();

    // Add a "Score" and "Distance" to the QStringList of result attributes names.
    resultAttributeNames.append("Score");
    resultAttributeNames.append("Distance");


    // Call the geocode async method with the provided geocode parameters on the locator task.

    task->geocodeWithParametersAsync("", parameters).then(this,[](const QList<GeocodeResult>& results)
    {
        // Only continue if we have results.
        if (!results.isEmpty())
        {
            // Loop thru the geocode results.
            for (const GeocodeResult& result : results)
            {
                // Display the results.
                qDebug() << "Found:" << result.label() << ", at" << result.displayLocation().toJson() <<
                    ", with score:" << result.score();
            }
        }

    });

Use API key access tokens

An API Key access token can be used to authorize access to ArcGIS services and portal items from your app, as well as to monitor access to those services. You can use a single access token for all requests made by your app, or assign individual access tokens for any classes that implements ApiKeyResource

Tutorials

Search for an address

Samples

Find address

Offline geocode

Find place

Reverse geocode

Display device location with autopan modes

Mobile map (search and route)

Services

Next steps

• Try a tutorial

  Step-by-step code examples

• Visit the samples

  Learn what is possible

• Explore the API

  Read more about classes