Finding Entities with the MapPoint Web Service Find APIs
(Page 1 of 4 )
In this fourth part of a five-part series on the MapPoint Web Service Find APIs, you will learn how to find custom entity types, how to find entities by properties, and more. This article is excerpted from chapter six of the book
Programming MapPoint in .NET, written by Chandu Thota (O'Reilly; ISBN: 0596009062). Copyright © 2007 O'Reilly Media, Inc. All rights reserved. Used with permission from the publisher. Available from booksellers or direct from O'Reilly Media.
Finding Custom Entity Types
MapPoint Web Service has a certain set of methods that find entities using their identities and properties, but these methods can only be used with the custom data uploaded to the MapPoint servers. These methods are particularly useful for queries that depend on nonspatial attributes. For example, if you upload all your ATMs to MapPoint servers and you want to display all ATMs in the city of Chicago, or only the ATM that has the unique identity of 13324, these methods can be either simple non-spatial queries or spatial queries. In this section, let’s look at these find methods that can be used with your custom data.
Find entity by identity
You can use the FindServiceSoap.FindByID method to find entities using their entity IDs. Like any other find method, this method takes a specification object of type FindByIDSpecification and returns a FindResultsobject. TheFindByIDSpecificationobject takes up to 500 IDs as input parameters. Table 6-6 shows the fields exposed on theFindByIDSpecificationobject.
Table 6-6. Fields exposed in the FindByIDSpecification object
| Field | Description |
| DataSourceName | Data source name as a string |
| EntityIDs | Array of unique entity IDs; only points of interest with matching entity IDs are returned, while the rest are ignored |
Filter | The filter (FindFilterobject) to apply to the results, which includes the specific entity type, properties, and values that the returned results must match |
Options | The search options (FindOptionsobject), which may include the range of results and a flag to identify which objects are desired in the returned results |
The following code shows how to use theFindByIDmethod:
//Create a Find Service proxy
FindServiceSoap findService = new FindServiceSoap();
//Assign credentials
. . .
//Define find by id specification
FindByIDSpecification findbyidspec = new FindByIDSpecification();
//Assign a data source name
findbyidspec.DataSourceName = "MapPoint.FourthCoffeeSample";
//Apply a filter for entity name
findbyidspec.Filter = new FindFilter();
findbyidspec.Filter.EntityTypeName = "FourthCoffeeShops";
//Now assign the entity IDs to find
int[] arrayID = {-21835, -21836};
findbyidspec.EntityIDs = arrayID;
//Call FindById method
FindResults foundResults;
foundResults = findService.FindByID(findbyidspec);
The found entities are returned in the same order that the entity IDs are passed in, but you can override this sorting behavior using theFindFilter.SortProperties. Assuming that you want to sort the ATMs in the previousFindByIDmethod by their associated bank name (assuming that there is a property calledParentBankName), the method call looks as follows:
//Create a Find Service proxy
FindServiceSoap findService = new FindServiceSoap();
//Assign credentials
. . .
//Define find by id specification
FindByIDSpecification findbyidspec = new FindByIDSpecification();
//Assign a data source name
findbyidspec.DataSourceName = "MapPoint.FourthCoffeeSample";
//Apply a filter for entity name
findbyidspec.Filter = new FindFilter();
findbyidspec.Filter.EntityTypeName = "FourthCoffeeShops";
//Specify what properties to be used to sort the found results
SortProperty[] sortproperties = new SortProperty[1];
sortproperties[0] = new SortProperty();
//Assign the property name to be sorted on
sortproperties[0].PropertyName = "ParentBankName";
//Specify the sort direction: Ascending or Descending
sortproperties[0].Direction = SortDirection.Descending;
//Assign sort specification to the find filter
findbyidspec.Filter.SortProperties = sortproperties;
//Now assign the entity ids to find
int[] arrayID = {-21835, -21836};
findbyidspec.EntityIDs = arrayID;
//Call FindById method
FindResults foundResults;
foundResults = findService.FindByID(findbyidspec);
As you can see, theSortPropertiesmethod is an array, so you can sort the resulting entities by more than one attribute if needed.
It is important to remember that the points of interest entity identities are not persisted from one version of the MapPoint Web Service to another, so if you hardcode the point of interest entity IDs into your application, when you upgrade to a newer MapPoint Web Service, your application may break. To make it easy to distinguish between positive and negative IDs, all negative entity IDs (such as entity ID -21835 for a coffee shop) are not persisted across versions, while the positive IDs are (such as entity ID 244 for the United States).
Next: Finding entity by properties >>
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.
|
|
