Geocoding Concept

• Using the forward geocoder in the Map Control Tutorial

  The section Searching for a Location within the Map Control Tutorial shows how to perform a forward geocode, which finds the map coordinates for a given address string.

• Autocomplete Geocoder Tutorial

  Use an AutocompleteGeocoder to find a list of full address suggestions for a given partial or full address string as you type, and get the map coordinates for the selected suggestion.

• Location Search Tutorial

  Use the LocationSearch API to find a location using different sources, such as geocoders, POI sources or custom data sources.

• Drill-down Geocoder Tutorial

  Use a DrillDownGeoCoder to perform a forward geocode by progressively 'drilling down' through decreasingly smaller search regions.

Forward geocoding is performed by the GeoCoderGeoCode method. This method has multiple overloads, supporting three different approaches to address input:

1. One-Line Geocode

   This approach works with a natural address; a full or partial address entered as a single string. Elements of the address (for example County) may be absent, and the ordering of address elements is not enforced, although it should match common practice for the country in question. This approach is suitable for a simple address search box UI element.

   C#

   Copy

   /* GeoCode(string Address, Country Country) */
   GeocodeAddress[] addr = 
   GeoCoder.GeoCode("20 Enterprise, Aliso Viejo, California", Country.USA);

   Note

   To perform database lookup, the GeoCoder needs to break the string into individual components (for example city, county) which can then be used to search the database. This process is called address decomposition. In some circumstances, the correct decomposition of a string might be ambiguous. This can result in the one-line geocoder overloads returning more or different results to the other approaches.

2. Structured Geocode

   The address is broken up into multiple strings representing address elements such as city or state. The ordering of the elements is fixed, and any missing element should be represented as an empty string. This approach is suitable for a structured address entry form.

   C#

   Copy

   /* GeoCode(string Address, string City, string Region, string PostCode, Country Country) */
   GeocodeAddress[] addr = GeoCoder.GeoCode("20 Enterprise", "Aliso Viejo", "", "", Country.USA);

3. Extended Structured Geocode

   The address is broken into a large set of strings representing individual components of the address, directly corresponding to their representation within the GBFS database. The ordering of the elements is fixed, and any missing element should be represented by an empty string. This is an advanced method that would only be suitable for applications implementing their own address decomposition methods.

   C#

   Copy

   /* GeoCode(int number, string prefix, string bf_type, string name, string af_type, string suffix, string city, string region, string postalCode, Country country) */
   GeocodeAddress[] addr = GeoCoder.GeoCode(14,"North","","Birmingham","Drive","","Christchurch","Canterbury","8024", Country.NewZealand);

Note
In addition to the multiple argument overloads demonstrated in the samples above, there are also single-argument overloads available for each approach, making use of dedicated helper classes OneLineGeoCodeArgs, StructuredGeoCodeArgs and ExtendedStructuredGeoCodeArgs.

The GeoCode method returns an array of GeocodeAddress objects. If a high confidence match has been made, this will typically only contain one result. In situations where there are potential matches, due to duplicate street names, missing address elements or ambiguous address decomposition, multiple results will be returned, sorted in descending order based on the confidence of the match.

Geocoding Example

/* We will geocode this address ... */
String address = "Technology Drive, Irvine";

/* ...using this method... */
GeocodeAddress[] results = GeoCoder.GeoCode(address, Country.USA);

/* ...finding these locations: */
for (int i = 0; i < results.Length; i++) {
    Console.WriteLine(results[i].ToString());
}

Reverse geocoding finds the closest address to a given latitude and longitude coordinate pair (defining a point on the earth). GeoBase can do this in three different ways:

1. Normal Reverse Geocoding

   In normal mode GeoBase will return the address that is perpendicularly closest to the coordinates specified, with a maximum distance of separation of 1° (approximately 111 km at the equator).

   For normal reverse geocoding use the method ReverseGeoCode(LatLon):

   C#

   Copy

   Address addr = GeoCoder.ReverseGeoCode(LatLon Location)

2. Full Reverse Geocoding

   In full mode supplementary information such as the link ID and closest-node coordinates are also returned. An optional cache of previous addresses can also be used to improve accuracy.

   For full reverse geocoding use the method ReverseGeoCodeFull(LatLon):

   C#

   Copy

   GeoCodeFull results = GeoCoder.ReverseGeoCodeFull(LatLon Location)

3. Aligned Reverse Geocoding

   In aligned mode GeoBase uses a combination of location and other optional arguments, such as heading and speed, to determine the most likely current address.

   As an illustration consider the figure below: the blue arrow represents the direction of travel (the heading) and the circles indicate the vehicle's coordinates. If normal geocoding is used, the address returned for the red circle will be Chenin Ave, even though the vehicle is clearly traveling along Sabino Canyon St. The use of heading information when in aligned mode allows this error to be avoided.

   

   For aligned reverse geocoding use the method ReverseGeoCodeFull(ReverseGeoCodeArgs):

   C#

   Copy

   GeoCodeFull results = GeoCoder.ReverseGeoCodeFull(ReverseGeoCodeArgs Args)

Reverse Geocoding Example

LatLon Location = new LatLon(34.0000, -118.0000);

var Arg = new ReverseGeoCodeArgs(Location){
    Heading = 350, Speed = 35
};

Address[] addr = new Address[3];

/* Normal Reverse Geocoding: */
addr[0] = GeoCoder.ReverseGeoCode(Location);

/* Full Reverse Geocoding: */
addr[1] = GeoCoder.ReverseGeoCodeFull(Location).Address;

/* Aligned Reverse Geocoding: */
addr[2] = GeoCoder.ReverseGeoCodeFull(Arg).Address;

Autocomplete geocoding finds a list of full address suggestions for a given partial or full address string. It is intended for use in address search fields that provide live suggestions as you type. Autocomplete geocoding is performed by the Geocode method. This method has multiple overloads. The recommended methods to use are:

• Geocode(AutocompleteGeocoderArgs)

  This is the most flexible and recommended method. It takes an AutocompleteGeocoderArgs object, which allows you to specify arguments such as countries, a query string, a LatLon location hint, and so on.

• Geocode(String, BoundingBox, LatLon, TimeSpan)

  This method allows you to search for partial address strings within all countries that intersect the provided BoundingBox. It also allows you to specify an optional LatLon location hint to bias results towards the given location (such as the center of a map view), and a timeout for the search.

• Geocode(String, Country, LatLon, TimeSpan)

  This method allows you to search for partial address strings within the specified country. It also allows you to specify an optional LatLon location hint to bias results towards the given location (such as the center of a map view), and a timeout for the search.

Autocomplete Geocoding Example

The example below uses the Geocode method that takes an AutocompleteGeocoderArgs object as an argument. This method provides the greatest flexibility.

AutocompleteGeocoderArgs args = new AutocompleteGeocoderArgs {
    Query = "20 Enterprise, Aliso", 
    Countries = new Country[]{Country.USA},
    Timeout = TimeSpan.FromSeconds(1)
};
AutocompleteGeocoderResult result = AutocompleteGeocoder.Geocode(args);
if (result.Status == SearchResult.SearchCompleted && result.Suggestions.Length == 0) {
   Console.WriteLine("No results found.");
} else if (result.Status == SearchResult.SearchCancelled) {
   Console.WriteLine("Search was canceled.");
} else {
   if (result.Status == SearchResult.TooManyResults) {
     Console.WriteLine("Too many results for the string provided. Further qualify the address to see further suggestions.");
   } else if (result.Status == SearchResult.Timeout) {
     Console.WriteLine("Search timed out.");
   } else if (result.Status == SearchResult.SearchCompleted) {
     Console.WriteLine("Search completed.");
   }
   foreach (AutocompleteGeocoderSuggestion suggestion in result.Suggestions) {
     Console.WriteLine(suggestion.ToString());
   }
}

Location searching finds map coordinates using different sources, such as geocoders, POI sources or custom data sources. The search query and other arguments are passed in via the LocationSearchArgs class. Location searching is provided by the Search method. By default, LocationSearch can use the AutocompleteGeocoder, the Geocoder, the ReverseGeocoder or POI sources, depending on the search arguments. If you want to use other search sources, for example a custom search source that you have created by implementing a subclass of the LocationSearchSource class, add them to the LocationSearch class via the AddSearchSource(LocationSearchSource) method.

Location Searching Example

The example below constructs a LocationSearchArgs object containing the arguments, passes the object to the LocationSearch and then uses the Search method to retrieve the results:

// Construct the Location Search arguments
var args = new LocationSearchArgs {
  // The queryString is defined outside this example.
  Query = queryString,
  // Specify the country, to speed up the search process. When not 
  // supplied, all countries are searched.
  Countries = new Country[] { Country.USA },
  // Set a location hint for the center of the map. This is
  // used to bias the results toward the area currently visible on 
  // the map.
  LocationHint = mapMain.Center,
  // Specify that the query is a prefix query, which means that 
  // the address does not need to be entered in its entirety.
  QueryForm = LocationSearch.QueryForm.Prefix,
  // Specify the types of results that should be returned, in this 
  // case any results that are based on an address search and
  // results found via reverse geocoding.
  ResultTypes = LocationSearch.ResultType.AllAddresses | LocationSearch.ResultType.ReverseGeocode 
};

// Supply the Location Search search args.
var search = new LocationSearch(args);

// Then retrieve the results.
LocationSearchResult output = search.Search();

Drill-down geocoding allows users to find map coordinates for a location by progressively 'drilling down' through decreasingly smaller search regions, narrowing down the search. Drill-down geocoding is performed by the methods provided by the DrillDownGeoCoder class. This class does not have a geocode method. Instead methods like GetRegions and GetStreets are used to present the user with a list of regions or streets at a given level and allow the users to narrow down their search for a particular location. When the user has selected a specific street and street number, the GetAddressLocation(Int32) method is used to find the exact location of the address.

See the 'Examples' section under DrillDownGeoCoder for an example on how the drill-down geocoder can be used.

• Address
• AutocompleteGeocoder
• DrillDownGeoCoder
• LatLon
• LocationSearch
• GeocodeAddress
• GeoCodeFull
• GeoCoder

Routing Concept