Search for an address

Learn how to find an address or place with a search bar and the Geocoding service.

Geocoding is the process of converting address or place text into a location. The Geocoding service can search for an address or a place and perform reverse geocoding.

In this tutorial, you use a search bar in the user interface to access the Geocoding service and search for addresses and places.

Prerequisites

The following are required for this tutorial:

An ArcGIS account to access API keys. If you don't have an account, sign up for free.
Your system meets the system requirements.
The ArcGIS Maps SDK for Qt, version 200.0.0 or later is installed. ArcGIS Maps SDK for Qt version 200.0.0 and later requires Qt 6.
The Qt 6 software development framework is installed.

Steps

Open the project in Qt Creator

To start this tutorial, complete the Display a map tutorial or download and unzip the solution.
Open the display_a_map project in Qt Creator.
If you downloaded the Display a map solution, set your API key.
An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.
1. Go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
2. In the Projects window, in the Sources folder, open the main.cpp file.
3. Modify the code to set the API key. Paste the API key, acquired from your dashboard, between the quotes. Then save and close the file.
  main.cpp
  Expand
  Use dark colors for code blocks
  36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 36 37 38 39 40 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41
  Change line
  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 // 2. API key: A permanent key that gives your application access to Esri // location services. Create a new API key or access existing API keys from // your ArcGIS for Developers dashboard (https://links.esri.com/arcgis-api-keys). const QString apiKey = QString("");
  Expand

Declare classes, member variables, functions, and signals

Double click on Sources > Display_a_map.h to open the file. Declare the classes shown.

Display_a_map.h
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.
namespace Esri::ArcGISRuntime {
class Map;
class MapQuickView;

class GraphicsOverlay;
class Graphic;
class LocatorTask;
class GeocodeResult;
class SuggestResult;
class TextSymbol;

Add the following two #include statements.

Display_a_map.h
Use dark colors for code blocks
Add line.Add line.
}

#include <QObject>

Q_MOC_INCLUDE("MapQuickView.h")

#include <QAbstractListModel>
#include "GeocodeParameters.h"

Add a Q_PROPERTY for the member variable suggestions.

Display_a_map.h
Use dark colors for code blocks
Add line.
class Display_a_map : public QObject
{
  Q_OBJECT
  Q_PROPERTY(Esri::ArcGISRuntime::MapQuickView* mapView READ mapView WRITE setMapView NOTIFY mapViewChanged)

  Q_PROPERTY(QAbstractListModel* suggestions READ suggestions NOTIFY suggestionsChanged)

Add the following public member functions with the Q_INVOKABLE macro to allow these to be invokable from the GUI.

Display_a_map.h
Use dark colors for code blocks
Add line.Add line.Add line.
public:
  explicit Display_a_map(QObject* parent = nullptr);
  ~Display_a_map() override;

  Q_INVOKABLE void geocode(const QString& query);
  Q_INVOKABLE void clearGraphics();
  Q_INVOKABLE void setSuggestions(const QString& text);

Add two new signal declarations.

Display_a_map.h
Use dark colors for code blocks
Add line.Add line.
signals:
  void mapViewChanged();

  void suggestionsChanged();
  void hideSuggestionView();

Declare the setupLocatorTask private method.

Display_a_map.h
Use dark colors for code blocks
Add line.
private:
  Esri::ArcGISRuntime::MapQuickView* mapView() const;
  void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);
  void setupViewpoint();

  void setupLocatorTask();

Add the following six private member functions and variables. Then save and close the header file.

Display_a_map.h
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
  void setupLocatorTask();

  Esri::ArcGISRuntime::Map* m_map = nullptr;
  Esri::ArcGISRuntime::MapQuickView* m_mapView = nullptr;

  void configureGraphic();
  QAbstractListModel* suggestions() const;
  Esri::ArcGISRuntime::GraphicsOverlay* m_graphicsOverlay = nullptr;
  Esri::ArcGISRuntime::LocatorTask* m_locatorTask = nullptr;
  Esri::ArcGISRuntime::Graphic* m_graphicResultLocation = nullptr;
  Esri::ArcGISRuntime::Graphic* m_graphicResultText = nullptr;
  Esri::ArcGISRuntime::TextSymbol* m_textSymbol = nullptr;
  QAbstractListModel* m_suggestListModel = nullptr;
  Esri::ArcGISRuntime::GeocodeParameters m_geocodeParams;

Include header files to access needed classes

In Projects, double click on Sources > Display_a_map.cpp to open the file and add the following #include statements.

Display_a_map.cpp
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
#include "Display_a_map.h"
#include "Map.h"
#include "MapTypes.h"
#include "MapQuickView.h"
#include "Point.h"
#include "Viewpoint.h"
#include "SpatialReference.h"
#include "TaskWatcher.h"

#include "AttributeListModel.h"
#include "Envelope.h"
#include "GeocodeResult.h"
#include "Graphic.h"
#include "GraphicListModel.h"
#include "GraphicsOverlay.h"
#include "GraphicsOverlayListModel.h"
#include "LocatorTask.h"
#include "SimpleMarkerSymbol.h"
#include "SimpleRenderer.h"
#include "SymbolTypes.h"
#include "SuggestParameters.h"
#include "SuggestResult.h"
#include "SuggestListModel.h"
#include "TextSymbol.h"

Include the following Qt classes.

Display_a_map.cpp
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
#include "AttributeListModel.h"
#include "Envelope.h"
#include "GeocodeResult.h"
#include "Graphic.h"
#include "GraphicListModel.h"
#include "GraphicsOverlay.h"
#include "GraphicsOverlayListModel.h"
#include "LocatorTask.h"
#include "SimpleMarkerSymbol.h"
#include "SimpleRenderer.h"
#include "SymbolTypes.h"
#include "SuggestParameters.h"
#include "SuggestResult.h"
#include "SuggestListModel.h"
#include "TextSymbol.h"

#include <QAbstractListModel>
#include <QGeoPositionInfoSource>
#include <QUrl>
#include <QUuid>

Create a locator task with geocode parameters

Geocoding is implemented with a locator, typically created by referencing a service such as the Geocoding service or, for offline geocoding, by referencing locator data contained in a mobile package. Geocoding parameters can be used to fine-tune the results, such as setting the maximum number of results or requesting additional attributes in the results.

Add the call to setupLocatorTask. This method will be implemented next.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.
Display_a_map::Display_a_map(QObject* parent /* = nullptr */):
    QObject(parent),
    m_map(new Map(BasemapStyle::ArcGISTopographic, this))
{

    setupLocatorTask();
Expand

Add code to begin implementing the setupLocatorTask method and initialize the auto-suggestion list. Within the method body, create a new LocatorTask with the Geocoding service URL, and set it to the m_locatorTask member variable.
A locator task is used to convert an address to a point (geocode) or vice-versa (reverse geocode). An address includes any type of information that distinguishes a place. A locator involves finding matching locations for a given address. Reverse-geocoding is the opposite and finds the closest address for a given location.
Create a SuggestParameters, instance and initialize it with three categories as shown. Then set max results to limit for the number of returned suggestion results to 5.

Configure GeocodeParameters, (m_geocodeParams). Add code to set the minimum match score and the attribute names for the results to be returned. Call suggestions on m_locatorTask and assign to m_suggestListModel.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    setupLocatorTask();

}
Display_a_map::~Display_a_map()
{
}

void Display_a_map::setupLocatorTask()
{
    const QUrl geocode_service("https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer");
    m_locatorTask = new LocatorTask(geocode_service, this);

    SuggestParameters suggestParams;
    const QStringList categories{"Address", "POI", "Populated Place"};
    suggestParams.setCategories(categories);
    suggestParams.setMaxResults(5);
    m_locatorTask->suggestions()->setSuggestParameters(suggestParams);

    m_geocodeParams.setMinScore(75);
    m_geocodeParams.setResultAttributeNames(QStringList {"Place_addr", "Match_addr"});
    m_suggestListModel = m_locatorTask->suggestions();
    emit suggestionsChanged();
Expand

Add code to the setupLocatorTask to connect to the geocode complete signal on the LocatorTask. Within the lambda body if statement, the code checks for geocoding results and verifies that the graphic exists. If both conditions are met, the result location is set as the graphic’s geometry and the attributes provided by the result are copied to the graphic. The map view display is centered on the graphic before making it visible.

The second code block in the if statement sets text symbol, sets the text graphic geometry for the geocoding result display location, sets attributes for the text graphic, and displays the graphic.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    m_geocodeParams.setMinScore(75);
    m_geocodeParams.setResultAttributeNames(QStringList {"Place_addr", "Match_addr"});
    m_suggestListModel = m_locatorTask->suggestions();
    emit suggestionsChanged();

    // connect to geocode complete signal on the LocatorTask
    connect(m_locatorTask, &LocatorTask::geocodeCompleted, this, [this](QUuid, const QList<GeocodeResult>& geocodeResults)
    {
        if (!geocodeResults.isEmpty() && m_graphicResultLocation)
        {
            // display geocode result label and position
            const GeocodeResult geocodeResult = geocodeResults.at(0);
            m_graphicResultLocation->setGeometry(geocodeResult.displayLocation());
            m_graphicResultLocation->attributes()->setAttributesMap(geocodeResult.attributes());
            constexpr double scale = 8000.0;
            m_mapView->setViewpointCenter(geocodeResult.extent().center(), scale);
            m_graphicResultLocation->setVisible(true);
            m_textSymbol->setText(geocodeResult.label());
            m_graphicResultText->setGeometry(geocodeResult.displayLocation());
            m_graphicResultText->attributes()->setAttributesMap(geocodeResult.attributes());
            m_graphicResultLocation->setVisible(true);
        }
    });
}
Expand

Create the auto-suggestion feature

Add a new setSuggestions method to implement the auto-suggestion feature. This generates a list of suggested addresses based on the user's input in the GUI text field.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    setupViewpoint();
    emit mapViewChanged();
}

void Display_a_map::setSuggestions(const QString& text)
{
    if (!m_suggestListModel)
        return;

    SuggestListModel* suggestListModel = dynamic_cast<SuggestListModel*>(m_suggestListModel);

    if (!suggestListModel)
        return;

    suggestListModel->setSearchText(text);
}
Expand

Revise the setupViewpoint method to respond to the user's mouse selection of an address from the list of suggested addresses.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
void Display_a_map::setupViewpoint()
{

    connect(m_mapView, &MapQuickView::mousePressed, this, [this](QMouseEvent& /* event */)
    {
        emit hideSuggestionView();
    });
Expand

Add text and marker graphics to identify location on map

Add the call to configureGraphic, which will be implemented in the next step.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.
    const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
    const Viewpoint viewpoint(center, 100000.0);
    m_mapView->setViewpoint(viewpoint);

    configureGraphic();
Expand

Implement the configureGraphic public method. Create a SimpleMarkerSymbol (blue square), initialize a Graphic and add that to a GraphicsOverlay. Then create TextSymbol, initialize a Graphic with that, and add it to the GraphicsOverlay. Then add the GraphicsOverlay to MapView.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    if (!suggestListModel)
        return;

    suggestListModel->setSearchText(text);
}

void Display_a_map::configureGraphic()
{
    if (m_graphicResultLocation)
        return;

    // create graphics overlay and add to map view
    m_graphicsOverlay = new GraphicsOverlay(this);

    // set a renderer on the graphics overlay
    SimpleRenderer* simpleRenderer = new SimpleRenderer(this);

    // Create a graphic and symbol to display the result location.
    SimpleMarkerSymbol* simpleMarkerSymbol = new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Square, QColor("blue"), 12.0, this);
    simpleRenderer->setSymbol(simpleMarkerSymbol);
    m_graphicResultLocation = new Graphic(this);
    m_graphicResultLocation->setSymbol(simpleMarkerSymbol);
    m_graphicsOverlay->graphics()->append(m_graphicResultLocation);

    // Create a graphic and symbol to display a label next to the result location
    m_textSymbol = new TextSymbol("", QColor("red"), 18.0, HorizontalAlignment::Center, VerticalAlignment::Bottom, this);
    m_graphicResultText = new Graphic(this);
    m_graphicResultText->setSymbol(m_textSymbol);

    m_graphicsOverlay->graphics()->append(m_graphicResultText);

    m_mapView->graphicsOverlays()->append(m_graphicsOverlay);
}
Expand

Add the Geocode method

An asynchronous geocode operation is required to find and return the location candidates for a given address and geocode parameters.

Add the geocode public method to geocode an address when the user clicks on that address in the auto-suggestion list.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
    m_graphicsOverlay->graphics()->append(m_graphicResultText);

    m_mapView->graphicsOverlays()->append(m_graphicsOverlay);
}

void Display_a_map::geocode(const QString& query)
{
    m_locatorTask->geocodeWithParameters(query, m_geocodeParams);
}
Expand

Add the suggestions method to register the value of m_suggestListModel as the value of the QML property suggestions.

Display_a_map.cpp
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
void Display_a_map::geocode(const QString& query)
{
    m_locatorTask->geocodeWithParameters(query, m_geocodeParams);
}

QAbstractListModel* Display_a_map::suggestions() const
{
    return m_suggestListModel;
}
Expand

Add the clearGraphics method. Then save and close the file.
Display_a_map.cpp
Expand
Use dark colors for code blocks
174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174 174

ArcGIS Maps SDK for Qt