Skip to main content

Search & Geocoding features

|

This guide explains how to use geocoding and reverse geocoding features to convert coordinates to addresses and vice versa, search along routes, and implement auto-suggestions.

Convert coordinates to addresses​

Transform geographic coordinates into detailed address information including country, city, street name, and postal code.

Search around a coordinate to get the corresponding address. The AddressInfo object contains information about the country, city, street name, street number, postal code, state, district, and country code.

Access individual fields using the getField method, or convert the entire address to a formatted string using the format method.

SearchPreferences prefs;
prefs.setThresholdDistance(50); // meters

Coordinates coordinates( 51.519305, -0.128022 );

// where results will be populated
LandmarkList results;

SearchService().searchAroundPosition(
    results,
    yourProgressListenerImpl,
    coordinates,
    String(), // don't filter by name
    prefs);

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl  ), 15000 );

// Get the operation's error (replace with your own error retrieval mechanism).
auto err = yourProgressListenerImpl->GetError();

if (err != KNoError || results.empty()) 
{
    GEM_INFO_LOG("No results found");
}
else 
{
    Landmark landmark = results.front();
    AddressInfo addressInfo = landmark.getAddress();

    auto country = addressInfo.getField(EAddressField::Country);
    auto city = addressInfo.getField(EAddressField::City);
    auto street = addressInfo.getField(EAddressField::StreetName);
    auto streetNumber = addressInfo.getField(EAddressField::StreetNumber);

    String fullAddress = addressInfo.format( {}, {});
    GEM_INFO_LOG("Address: %s", fullAddress.toStdString().c_str());
}

Convert addresses to coordinates​

Convert address components into geographic coordinates using a hierarchical structure.

Addresses follow a tree-like structure where each node is a Landmark with a specific AddressDetailLevel. The hierarchy starts with country-level landmarks, followed by cities, streets, and house numbers.

danger

The address structure varies by country. Some countries do not have states or provinces. Use the getNextAddressDetailLevel method from the GuidedAddressSearchService class to get the next available levels in the address hierarchy.

Search for countries​

Search at the country level to find the parent landmark for hierarchical address searches.

LandmarkList results;

GuidedAddressSearchService().search(results, 
    Landmark(), // default landmark
    String("Germany"), // filter
    EAddressDetailLevel::AD_Country, // detail level Country
    yourProgressListenerImpl
);

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl  ), 15000 );

auto err = yourProgressListenerImpl->GetError();

if (err != KNoError || results.empty()) 
{
    GEM_INFO_LOG("No results found");
}
else 
{
    // do something with result
}

This method restricts results to country-level landmarks and works with flexible search terms regardless of language.

Search through the address structure from country to house number using parent landmarks and detail levels.

Possible EAddressDetailLevel values: AD_NoDetail, AD_Country, AD_State, AD_County, AD_District, AD_City, AD_Settlement, AD_PostalCode, AD_Street, AD_StreetSection, AD_StreetLane, AD_StreetAlley, AD_HouseNumber, AD_Crossing.

Search for child landmarks step by step:

auto countryLandmark = GuidedAddressSearchService().getCountryLevelItem("ESP");
GEM_INFO_LOG("Country: %s", countryLandmark.getName());

// Use the address search to get a landmark for a city in Spain (e.g., Barcelona).
LandmarkList cities;

GuidedAddressSearchService().search(cities,
    countryLandmark,
    "Barcelona",
    EAddressDetailLevel::AD_City,
    yourProgressListenerImpl
    );

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl  ), 15000 );

if (cities.empty()) return;
GEM_INFO_LOG("City: %s", cities.front().getName());

yourProgressListenerImpl = StrongPointerFactory<YourProgressListenerImpl>();
// Use the address search to get a predefined street's landmark in the city (e.g., Carrer de Mallorca).
LandmarkList streets;

GuidedAddressSearchService().search(streets,
    cities.front(),
    "Carrer de Mallorca",
    EAddressDetailLevel::AD_Street,
    yourProgressListenerImpl
    );

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl  ), 15000 );

if (streets.empty()) return;
GEM_INFO_LOG("Street: %s", streets.front().getName());

yourProgressListenerImpl = StrongPointerFactory<YourProgressListenerImpl>();
// Use the address search to get a predefined house number's landmark on the street (e.g., House Number 401).
LandmarkList houseNumbers;

GuidedAddressSearchService().search(houseNumbers,
    streets.front(),
    "401",
    EAddressDetailLevel::AD_HouseNumber,
    yourProgressListenerImpl
    );

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl  ), 15000 );

if (houseNumbers.empty()) return;
GEM_INFO_LOG( "House number : %s", houseNumbers.front().getName());

// Now you can use the resulted house number Landmark to Navigate to it for instance

The getCountryLevelItem method returns the root node for the specified country code. If the country code is invalid, it returns empty. Alternatively, use the search method with EAddressDetailLevel::AD_Country.

Access Wikipedia information​

Retrieve Wikipedia content for search results to provide additional context about landmarks.

Perform a standard search, then call ExternalInfo::requestWikiInfo to get Wikipedia descriptions for identified landmarks.

Search along routes​

Find landmarks and points of interest along a predefined route.

Use SearchService().searchAlongRoute to search for landmarks within a specified distance from the route:

SearchService().searchAlongRoute(
    results,
    yourProgressListenerImpl,
    route);

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl ), 15000 );

auto err = yourProgressListenerImpl->GetError();

if (err != KNoError || results.empty()) 
{
    GEM_INFO_LOG("No results found");
}
else 
{
    // do something with results
}

Use SearchPreferences::setThresholdDistance to specify the maximum distance from the route for landmarks to be included. Configure other SearchPreferences fields based on your use case.

Last updated on