Section 6.1. Understanding Find APIs

6.1. Understanding Find APIs

If you remember from our discussion in Chapter 5, the Find Service endpoint is located at the FindService.asmx, and the APIs available for Find Service are exposed via the FindServiceSoap class in the Web Service proxy (Reference.cs or Reference.vb). The FindServiceSoap class contains a number of find-related methods used for finding places, addresses, nearby points, and so on. Table 6-1 shows the methods exposed on the FindServiceSoap class.

Table 6-1. Methods available on the FindServiceSoap class

Method	Description
Find	Finds geographic locations in a specified data source based on a place name. Returns an array of results as a FindResults object. Maximum returned values is 500. Default number of returned results is 25.
FindAddress	Finds geographic locations in a specified data source based on an address. Returns an array of possible results as a FindResults object. Maximum returned values is 100. Default number of returned results is 25.
FindByID	Finds points of interest based on entity ID. The found results are returned as a FindResults object.
FindByProperty	Finds points of interest based on predefined or custom properties. This method is independent of the location information such as distance and latitude/longitude. The found results are returned as a FindResults object.
FindNearby	Finds points of interest within a specified distance of a given latitude and longitude coordinate; returns an array of found points of interest ordered by proximity to a selected point as a FindResults object. Maximum returned values is 500. Default number of returned results is 25.
FindNearRoute	Finds points of interest within a specified distance from a route. The found results are returned as a FindResults object.
FindPolygon	Finds polygons in a specified data source, based on a FindPolygonSpecification object. The found results are returned as a FindResults object.
GetLocationInfo	Finds geographic entities and addresses for a specified latitude and longitude coordinate (also known as reverse geocoding). Returns an array of locations (Location objects). Maximum returned values is 250.
ParseAddress	Parses a specified address string and returns an Address object.

In this chapter, we will go over these methods in detail; first, let's look at some basic concepts.

6.1.1. The Anatomy of Find Methods

The FindServiceSoap class contains the methods related to find functionality, such as Find (place), FindAddress, FindNearby, and so on. Choose the appropriate find method based on your application's needs. All find methods share a common signature pattern as shown in the following example, where XXX can be an address or a nearby entity):

         FindResults FindXXX( FindXXXSpecifiction )

A find method, no matter what type of find it is, always returns the results in the form of the FindResults instance, which tells you how many matches are found for your find query along with the actual location matches. The actual location matches are represented as an array of FindResult class instances, each of which contains an instance of matched location as a Location object that provides information such as latitude/longitude, address, entity type, and the confidence score of the location match. It is important to note that Location instances in MapPoint Web Service expose the actual latitude and longitude information of the physical location and a corresponding best possible map view associated with it.

Unlike the consistent output returned by all find methods, the input argument is unique to each find method type, so the specification corresponding to each find type is represented by specific types. For example, if you are using the FindAddress method, use the FindAddressSpecification object as an input argument; if you are using the FindNearby method, use the FindNearbySpecification object as an input argument. Each input specification object contains three core parts:

Data source name

This field is found across all specification objects for all find methods and indicates which data source to use for the find.

Find-type specific arguments

This field is unique to each find method and includes arguments such as input address for an address search, place name for a place search, and so forth.

Optional FindOptions object

This field is found across all the specification objects for all find methods and can be used to control the output behavior.

For example, the FindAddressSpecification object, which is passed to the FindAddress method to find an address, contains the following three fields:

DataSourceName

A string value that represents the data source to be used for the address search (such as MapPoint.NA and MapPoint.EU).

InputAddress

An instance of the Address class that represents the input address to be used in the search.

Options

An instance of the FindOptions class that can be used to control the behavior of the results returned by any find method. This argument is optional.

Any specification object used in the find method is consistently modeled in this format.

By now, I'm sure you are wondering how the FindOptions object can alter the behavior of the results returned by the find method. Let's look briefly at this object so that you understand its purpose. The FindOptions object contains the following fields:

Range

This field can be used to control the number of returned matches and the starting index of the returned results. For example, if you are searching for a place and your search yields 200 matches, you can request to return only the top 10 results. Along the same lines, you can also request a range of results starting with any valid index (such as from 21 to 30), which is very useful if you are displaying the search results from multiple pages (the typical pagination feature for displaying data). This field is of type FindRange.

ResultMask

By default, all find methods return latitude/longitude, entity type information, address, and best map view information for each matched location of the input query. You can use this field to mask the unwanted information returned from a find method. For example, if you are searching for a place and looking only for latitude/longitude information, you can prevent the find method from returning any other information using this mask. The ResultMask field is of type FindResultMask and is an enumeration.

SearchContext

This field indicates the entity ID within which you want to perform your search. In this case, the entity ID represents a geographic area to which you want to limit your search. Assigning an entity to provide a search context returns more relevant matches faster. This field is of type Integer.

ThresholdScore

Each result returned by any find method contains a score indicating the level of confidence in the match. Using this field, you can filter out the low-confidence results below the specified ThresholdScore. This field is of type Double, and the valid values are between zero and one (low confidence to high confidence).

Using the FindOptions object, you can tailor the results returned by the find method according to your application's needs. There is one more interesting tidbit you may want to know about the FindOptions object: when you use it in your find method calls, you actually positively impact the performance (and possibly the economics) of your application. I will discuss the details at the end of this chapter in the section on optimizing your find calls performance.

Now that you know the anatomy of the Find Service, let's look briefly at entities and the entity relationships model in MapPoint Web Service before we get into coding aspects of the Find Service.