MapPoint Web Service Find APIs - The Anatomy of Find Methods
(Page 2 of 4 )
The FindServiceSoapclass contains the methods related to find functionality, such asFind (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 FindResultclass instances, each of which contains an instance of matched location as aLocationobject that provides information such as latitude/longitude, address, entity type, and the confidence score of the location match. It is important to note thatLocationinstances 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 theFindAddressmethod, use theFindAddressSpecificationobject as an input argument; if you are using theFindNearbymethod, use theFindNearbySpecificationobject 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 FindOptionsobject
This field is found across all the specification objects for all find methods and can be used to control the output behavior.
For example, theFindAddressSpecificationobject, which is passed to theFindAddressmethod 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 asMapPoint.NAandMapPoint.EU).
InputAddress
An instance of theAddressclass that represents the input address to be used in the search.
Options
An instance of theFindOptionsclass 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 theFindOptionsobject 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. TheFindOptionsobject 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 typeFindRange.
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. TheResultMaskfield is of typeFindResultMaskand 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 typeInteger.
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 specifiedThresholdScore. This field is of typeDouble, and the valid values are between zero and one (low confidence to high confidence).
Using theFindOptionsobject, 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 theFindOptionsobject: 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.
Next: Understanding Entities and Entity Relationships >>
More BrainDump Articles
More By O'Reilly Media
|
 This article is excerpted from chapter six of the book Programming MapPoint in .NET, written by Chandu Thota (O'Reilly; ISBN: 0596009062). Check it out today at your favorite bookstore. Buy this book now.
|
|
