Geocoding and reverse geocoding

You can use geocoding and reverse geocoding to translate an address into coordinates on a map or convert location coordinates to a human readable address. Geocoding converts an address string to a latitude and longitude coordinate, and reverse geocoding converts a coordinate to an address.

  • A restaurant locater can find coordinates of street addresses and display nearby locations on a map. This app can use geocoding to convert an address into longitude and latitude coordinates.

  • A social networking app can post a user's location in a status update as an address. In this case, the app can use reverse geocoding to convert the coordinates of the current location to a friendly address before posting the update.

  • You can search with free-form text input by using QGeoAddress::setText() and passing the QGeoAddress to the geocode() function. The geocode() function uses text() to search, if it has been set. If text() hasn't been set, the geocode() function uses a combination of the other address fields.

You can use the following QtLocationSubset classes for geocoding and reverse geocoding:

  • QGeoAddress

    An address that can be parsed and presented to the user in any format or automatically formatted according to the country code.

  • QGeoCoordinate

    A geographic position on the earth (latitude, longitude, and optionally, altitude).

  • QGeoPlace

    A geographic place, which is defined as an address and its corresponding geographic position.

  • QGeoSearchManager

    Geocoding and reverse geocoding functionality.

  • QGeoSearchManagerEngine

    Interface and convenience functions for QGeoServiceProvider plug-ins.

  • QGeoSearchReply

    Search results in the form of a list of places, in response to a query through QGeoSearchManager.

The reverseGeocode() and geocode() functions always return a QGeoSearchReply object. The QGeoSearchReply may respond immediately if there's an error, or you may have to wait for the result by connecting to the error() and finished() signals of the QGeoSearchReply.

You can also connect to the error() and finished() signals of the QGeoSearchManager, which takes a reference to the QGeoSearchReply object returned by your geocode() or reverseGeocode() call.

Find coordinates of an address (geocoding)

You can get a QGeoCoordinate object for a street address using the geocode() function of the QGeoSearchManager class.

The geocode() function immediately returns a  QGeoSearchReply object, which is a placeholder for a list of addresses defined as QGeoPlace objects. The call to geocode() is asynchronous and you should wait for the finished() signal from QGeoSearchReply to be emitted before using the QGeoSearchReply object.

If the call to geocode() isn't successful, the error() signal of QGeoSearchReply is emitted. You can connect to this signal to get notified about errors and you can use the error type as well as the error string to present a toast or a dialog box to the user.

If the call to geocode() is successful, the  QGeoSearchReply contains a list of places(). The places() are returned as  QGeoPlace objects. Each QGeoPlace represents a combination of coordinate and address data.

You can use the QGeoPlace object to find the address of a place in the form of a QGeoAddress. You can use this data to present an address to the user. You can also present the exact coordinates of the address to the user in your app using the coordinate of a place.

The following code sample demonstrates how to use geocode() function to find the coordinates of an address:

// Initialize QGeoSearchManager
QStringList serviceProviders = 
    QGeoServiceProvider::availableServiceProviders();

if ( serviceProviders.size() ) {
	// serviceProvider is a QGeoServiceProvider *
    serviceProvider = new QtMobilitySubset::QGeoServiceProvider( 
                      serviceProviders.at(0) ); 
	// searchManager is a QGeoSearchManager *
    searchManager = serviceProvider->searchManager();
}

// ...

// Request geocoding
QGeoSearchReply *reply = searchManager->geocode(myQGeoAddress, 
                                                myQGeoBoundingArea);
bool finished_connected = QObject::connect(reply,
	 SIGNAL(finished()),
	 this,
	 SLOT(readGeocode()));

     if (finished_connected) {
       // Signal was successfully connected.

     } else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be
        // a critical situation for your app! Make sure
        // you know exactly why this has happened. Add 
        // some code to recover from the lost connection 
        // below this line.
     }

bool error_connected = QObject::connect(reply,
	 SIGNAL(error(QGeoSearchReply::Error, QString)),
	 this,
	 SLOT(geocodeError(QGeoSearchReply::Error, QString)));

     if (error_connected) {
       // Signal was successfully connected.

     } else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be
        // a critical situation for your app! Make sure
        // you know exactly why this has happened. Add 
        // some code to recover from the lost connection 
        // below this line.    
     }
}

// ...

//Implement SLOTs
MyClass::readGeocode(){
	// Handle geocoded coordinates from reply
	...
	delete reply;
}

MyClass::geocodeError(QGeoSearchReply::Error error, 
    QString errorString){
	// Handle error and error string 
	...
	delete reply;
}

Find an address using coordinates (reverse geocoding)

When your app retrieves the location of a device or obtains a location in the form of a QGeoCoordinate object, you can get a street address for these coordinates by using the  reverseGeocode() function of QGeoSearchManager.

The reverseGeocode() function immediately returns a QGeoSearchReply object, which is a placeholder for a list of addresses defined as QGeoPlace objects. The call to reverseGeocode() is asynchronous and you should wait for the finished() signal from QGeoSearchReply to be emitted before using the QGeoSearchReply object.

If the call to reverseGeocode() isn't successful, the error() signal of QGeoSearchReply is emitted. You can connect to this signal to get notified about errors and you can use the error type, as well as the error string, to present a toast or a dialog box to the user.

If the call to reverseGeocode() is successful, the  QGeoSearchReply contains a list of places(). The places() are returned as  QGeoPlace objects. Typically only one place is returned if the request was for the geographic coordinates of a specific address. If the search term was more vague, like a city name, then the list may be longer.

You can use the QGeoPlace object to find the address of a place in the form of a QGeoAddress. You can use this data to present an address to the user. You can also present the exact coordinates of the address to the user in your app using the coordinate of a place. The reverseGeocode() function may return a different set of coordinates than you provided if the address is not exactly found at the original coordinates but is the closest address to those coordinates.

The following code sample demonstrates how to use reverseGeocode() function to find an address using coordinates:

// Initialize QGeoSearchManager
QStringList serviceProviders = 
    QGeoServiceProvider::availableServiceProviders();

if ( serviceProviders.size() ) {
	// serviceProvider is a QGeoServiceProvider *
    serviceProvider = new QtMobilitySubset::QGeoServiceProvider( 
                      serviceProviders.at(0) ); 
	// searchManager is a QGeoSearchManager *
    searchManager = serviceProvider->searchManager();
}

// ...

// Request reverse geocoding
QGeoSearchReply *reply = 
    searchManager->reverseGeocode(myQGeoCoordinate, 
    myQGeoBoundingArea);

bool finished_connected = QObject::connect(reply,
	 SIGNAL(finished()),
	 this,
	 SLOT(readReverseGeocode()));

     if (finished_connected) {
       // Signal was successfully connected.

     } else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be
        // a critical situation for your app! Make sure
        // you know exactly why this has happened. Add 
        // some code to recover from the lost connection 
        // below this line.
     }

bool error_connected = QObject::connect(reply,
	 SIGNAL(error(QGeoSearchReply::Error, QString)),
	 this,
	 SLOT(reverseGeocodeError(QGeoSearchReply::Error, QString)));

     if (error_connected) {
       // Signal was successfully connected.

     } else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be
        // a critical situation for your app! Make sure
        // you know exactly why this has happened. Add 
        // some code to recover from the lost connection 
        // below this line.
     }
}

// ...

//Implement SLOTs
MyClass::readReverseGeocode(){
	// Handle reverse geocoded address from reply
	...
	delete reply;	
}

MyClass::reverseGeocodeError(QGeoSearchReply::Error error, 
    QString errorString){
	// Handle error and error string 
	...
	delete reply;
}

Last modified: 2013-12-21



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus