FindNearby Method Basics for MapPoint Web Service 3.5

  • Article

 

IMPORTANT: MapPoint Web Service was retired on November 18, 2011. Please see Bing Maps for a list of current Bing Maps APIs.

Alan Paulin and Frank Morrison
Microsoft Corporation

January 2004
Revised April 2004

Applies to:
   Microsoft® MapPoint® Web Service version 3.5

Summary: Learn basic concepts and techniques for finding nearby points of interest using Microsoft MapPoint Web Service. (26 printed pages)

Contents

Introduction
FindNearbySpecification Object
Filter Property
Options Property
Examples
Conclusion

Introduction

The FindServiceSoap.FindNearby method is a powerful feature of the MapPoint Web Service SOAP API. Using the FindNearby method, you can add the power of proximity searching to your Web site or solution. You can perform proximity searches on regularly-updated commercial data, such as Yellow Pages listings, which are included with a MapPoint Web Service subscription. Additionally, you can upload custom data and use FindNearby in custom store-locator and brand-finder applications.

The FindNearby method takes one parameter, specification, which contains a FindNearbySpecification object and returns results in an instance of the FindResults class. The signature for the FindNearby method is as follows:

Microsoft Visual Basic .NET
Public NotOverridable Function FindNearby ( ByVal specification
   As [Namespace].FindNearbySpecification )
   As [Namespace].FindResults
      Member of [Namespace].FindServiceSoap

Microsoft Visual C# .NET
public [Namespace].FindResults FindNearby ( 
   [Namespace].FindNearbySpecification specification )
      Member of [Namespace].FindServiceSoap

This article first discusses the properties of FindNearbySpecification, focusing on techniques for retrieving relevant results, and then provides examples in Microsoft® Visual Basic® .NET and Microsoft Visual C#® .NET that illustrate how to use FindNearby.

FindNearbySpecification Object

FindNearbySpecification has a number of properties that you can specify, including the type of entity you're searching for, the search radius, and the number of results that are returned. FindNearbySpecification has the following properties:

  • DataSourceName (System.String)
    Contains a string that represents the name of the data source in which to search for points of interest. In this article, we'll use the MapPoint.FourthCoffeeSample data source because it contains entities with an assortment of properties that we'll use to illustrate the features of the FindNearby method.
    To discover the data sources that are available in MapPoint Web Service, use the CommonServiceSOAP.GetDataSourceInfo Method.
    This method returns the names of all publicly available data sources, and their versions and capabilities, in addition to private, custom data sources that are associated with your account. You can use FindNearby only with data sources whose capability property is set to CanFindNearby. For more information about available data sources, see the MapPoint Web Service SDK, version 3.5.
  • Distance (System.Double)
    Identifies the radius of the search area, stored as a Double. Distance must be greater than 0 and no more than 80.4672 kilometers (50 miles). Distance is measured in units defined by the DistanceUnit enumeration, which has a default value of DistanceUnit.Kilometer. For more information, see DistanceUnit Enumeration.
  • LatLong (LatLong)
    Specifies the center point of the radius in which to search. Often, the latitude and longitude coordinates are passed when the LatLong class is derived from a previous call to the FindServiceSOAP.FindAddress method and are based on an address provided by an end user. The examples later in this article assume that this step has already occurred.
  • Filter (FindFilter)
    Narrows the information returned in FindResults. This property is discussed in detail in the following section.
  • Options (FindOptions), optional
    Specifies additional restrictions and parameters for the information returned in FindResults. This property is discussed in detail later in this article.

Filter Property

The Filter property (a FindFilter object) is used to narrow the information returned in FindResults. With FindFilter, you can restrict the results of your proximity search to specific property values within your data, and if you choose to, sort the results by property values.

The FindFilter class has the following properties:

  • EntityTypeName (System.String)
    Represents the category of data on which to perform the spatial query.
    The data source we're using in this article, MapPoint.FourthCoffeeSample, contains only one entity type, like all private data sources that you upload to MapPoint Web Service. Other MapPoint Web Service data sources, such as NavTech.NA, contain a wide variety of entity types. For more information, see MapPoint Data Source Entity Types and Properties.
    To discover the entity type names, property names, and property data types that are associated with a particular data source, use the CommonServiceSoap.GetEntityTypes Method.

  • PropertyNames (System.String[]), optional
    Restricts the properties that are included in the returned result. The PropertyNames property consists of an array of String values. If you do not specify PropertyNames, FindNearby returns all available properties for the specified data source, which can slow query response times. Property names that you use in PropertyNames must be valid for the data source specified in FindNearbySpecification.DataSourceName. The following code demonstrates how to restrict the properties returned by a FindNearby method call.

    Microsoft Visual Basic .NET
   Dim myPropertyNames(5) As String
   myPropertyNames(0) = "Name"
   myPropertyNames(1) = "AddressLine"
   myPropertyNames(2) = "PrimaryCity"
   myPropertyNames(3) = "Phone"
   myPropertyNames(4) = "StoreType"
   myPropertyNames(5) = "Open"
   myFindFilter.PropertyNames = myPropertyNames

Microsoft Visual C# .NET
   string[] myPropertyNames = new string[6];
   myPropertyNames[0] = "Name";
   myPropertyNames[1] = "AddressLine";
   myPropertyNames[2] = "PrimaryCity";
   myPropertyNames[3] = "Phone";
   myPropertyNames[4] = "StoreType";
   myPropertyNames[5] = "Open";
   myFindFilter.PropertyNames = myPropertyNames;

  • WhereClause (WhereClause), optional
    Specifies name/value pairs that are used to filter the search results. This property is discussed in detail in the following section.

  • Expression (FilterExpression), optional
    Specifies a filter expression that is used to filter the search results. This property is discussed in detail later in this article.

  • SortProperties (SortProperty[]), optional
    Specifies how search results are ordered. This property is discussed in detail later in this article.

The Expression and WhereClause properties offer two ways to eliminate unwanted entities based on property values. Each FindNearby query can contain either a WhereClause or an Expression property, but not both. Additionally, you can order the results by property values with the optional SortProperties property.

WhereClause Property

With the optional WhereClause property (a WhereClause object), you can specify up to 10 name/value pairs to filter entities based on the values of their properties. Entities within the search radius are excluded from FindResults if the value of each search property does not match the value you specify.

The WhereClause class has the following properties:

  • SearchProperties (EntityPropertyValue[])
    Contains an array of EntityPropertyValue objects consisting of name/value pairs on which to search. The EntityPropertyValue class has the following properties:

    • Name (System.String)—Contains the name of a property that you want to search for. The Name property must be a valid property for the data source specified in FindNearbySpecification.DataSourceName.
    • Value (System.Object)—Contains a value for the property specified in Name. The data type of the object specified in Value must match the data type of the property specified in Name.

    The following code example shows a WhereClause query that returns results containing only entities whose value for "DeliveryAreas" is equal to 98052 and whose value for "AcceptsOnlineOrders" is equal to true. "AcceptsOnlineOrders" is a Boolean property, so its Value property is also Boolean. "DeliveryAreas" is a Keyword property, which are multi-valued String properties. Each entity can have multiple values for "DeliveryAreas".

    Microsoft Visual Basic .NET
   Dim mySearchProperties(1) As EntityPropertyValue
   mySearchProperties(0) = New EntityPropertyValue
   mySearchProperties(0).Name = "DeliveryAreas"
   mySearchProperties(0).Value = "98052"
   mySearchProperties(1) = New EntityPropertyValue
   mySearchProperties(1).Name = "AcceptsOnlineOrders"
   mySearchProperties(1).Value = true
   myWhereClause.SearchProperties = mySearchProperties

Microsoft Visual C# .NET
   EntityPropertyValue[] mySearchProperties = 
      new EntityPropertyValue[2];
   mySearchProperties[0] = new EntityPropertyValue();
   mySearchProperties[0].Name = "DeliveryAreas";
   mySearchProperties[0].Value = "98052";
   mySearchProperties[1] = new EntityPropertyValue();
   mySearchProperties[1].Name = "AcceptsOnlineOrders";
   mySearchProperties[1].Value = true;
   myWhereClause.SearchProperties = mySearchProperties;

    To discover the property names and data types for each entity type in a particular data source, use the CommonServiceSoap.GetEntityTypes Method.

  • SearchOperator (SearchOperatorFlag enumeration), optional
    Specifies whether the entities returned in FindResults must match all of the values specified in SearchProperties (the SearchOperator.And flag) or any of the values specified in SearchProperties (the SearchOperator.Or flag). The default is SearchOperator.And.

Expression Property

With the optional Expression property (a FilterExpression object), you can specify a complex filter expression to limit the information returned in FindResults. The Expression property, which is new with MapPoint Web Service 3.5, offers all of the functionality of WhereClause in addition to new functionality. Expression is more powerful than WhereClause because it allows comparison operators that the WhereClause does not, such as greater than ( > ). Expression also allows AND and OR to be used simultaneously, which is not possible with WhereClause.

The FilterExpression class has the following properties:

  • Text (System.String)
    Contains the body of the search expression, which evaluates to true or false for each entity. Only entities whose Expression property evaluates to true are included in FindResults. The syntax of Text is similar to Structured Query Language (SQL). Property names used in Text must be valid for the data source specified in FindNearbySpecification.DataSourceName.

In the following example, three properties, "StoreType" (which is used twice), "Close", and "AcceptsCoffeeCards", are compared using two comparison operators: equals ( = ) and greater than ( > ). Three placeholders, {0}, {1}, and {2}, represent the values in the Parameters array with which the properties will be compared.

Microsoft Visual Basic .NET
   Dim myText As String
   myText = "(StoreType = {0} OR StoreType = {1}) AND " & _
      "Close > {3) AND AcceptsCoffeeCards"
   myFilterExpression.Text = myText

Microsoft Visual C# .NET
   string myText = "(StoreType = {0} OR StoreType = {1}) AND " +
      "Close > {3) AND AcceptsCoffeeCards";
   myFilterExpression.Text = myText;

  • Parameters (System.Object[]), optional
    Contains the values that the Text property references with placeholders. The type of each object must be consistent with the data type of the property with which it is being compared. The Parameters property is optional only if no placeholders are referenced in the Text property.
    Continuing with the previous example, the expression can be read as follows—entities are returned only if they meet the following criteria:

    • "StoreType" is either Coffee Shop or Drive-Thru.
    • "Close" is greater than 1900.
    • "AcceptsCoffeeCards" is true.

    Notice that because "AcceptsCoffeeCards" is a Boolean property, it does not require a comparison operator and parameter value. The "Close" property has a data type of Long; thus, the third parameter is an Integer (it could be a Long as well).
    For a full list of comparison operators, logical operators, and restrictions on the FilterExpression property, see FilterExpression.Text Property. For a full list of compatible data types, see FilterExpression.Parameters Property.

    Microsoft Visual Basic .NET
   Dim myParameters(2) As Object
   Dim myFirstParameter As String
   myFirstParameter = "Coffee Shop"
   myParameters(0) = myFirstParameter
   Dim mySecondParameter As String
   mySecondParameter = "Drive-Thru"
   myParameters(1) = mySecondParameter
   Dim myThirdParameter As Integer
   myThirdParameter = 1900
   myParameters(2) = myThirdParameter
   myFilterExpression.Parameters = myParameters
   myFindFilter.Expression = myFilterExpression

Microsoft Visual C# .NET
   object[] myParameters = new object[3];
   string myFirstParameter = "Coffee Shop";
   myParameters[0] = myFirstParameter;
   string mySecondParameter = "Drive-Thru";
   myParameters[1] = mySecondParameter;
   int myThirdParameter = 1900;
   myParameters[2] = mySecondParameter;
   myFilterExpression.Parameters = myParameters;

SortProperties Property

The optional SortProperties property consists of an array of one to three SortProperty objects. When you use SortProperties, the entities in FindResults are ordered by SortProperties, instead of the default ordering by proximity to FindNearbySpecification.LatLong.

The SortProperty class has the following properties:

  • PropertyName (System.String)
    Contains the name of the property by which to order the results. The PropertyName property must be a valid property for the data source that you specified in FindNearbySpecification.DataSourceName.

  • Direction (SortDirection enumeration), optional
    Specifies whether the results are sorted in ascending or descending order. The default is SortDirection.Ascending.

    The following code demonstrates how to sort the properties returned by a FindNearby method call.

    Microsoft Visual Basic .NET
   Dim mySortProperties(0) As SortProperty
   Dim mySortProperty As New SortProperty
   mySortProperty.PropertyName = "Close"
   mySortProperty.Direction = SortDirection.Descending
   mySortProperties(0) = mySortProperty
   myFindFilter.SortProperties = mySortProperties

Microsoft Visual C# .NET
   SortProperty[] mySortProperties = new SortProperty[1];
   SortProperty mySortProperty = new SortProperty();
   mySortProperty.PropertyName = "Close";
   mySortProperty.Direction = SortDirection.Descending;
   mySortProperties[0] = mySortProperty;
   myFindFilter.SortProperties = mySortProperties;

    Note   The data type of the PropertyName property affects how the results are sorted. Sorting using a String property, such as "StoreType", sorts the results alphabetically, while sorting using a Long or Double property, such as "Close", sorts the results numerically.

When using SortProperties in a FindNearby query, note that all entities within the radius you specify in FindNearbySpecification.Distance are considered before the results are sorted. The FindResults.NumberFound property indicates the total number of results found within the search radius (to a maximum of 500). If NumberFound is higher than Options.Range.Count (discussed in following section) and SortProperties is specified, entities extremely close to FindNearbySpecification.LatLong may not be included in FindResults.

Options Property

With the optional Options property (a FindOptions class), you can specify additional restrictions and parameters for the results that are returned by FindNearby.

The FindOptions class has the following properties:

  • SearchContext (System.Integer), not used
    Ignored by FindNearby.

  • ThresholdScore (System.Double), not used
    Ignored by FindNearby.

  • Range (FindRange), optional
    Contains a FindRange object that you can use to specify a range of the total results to return. The FindRange object has the following properties:

    • Count (System.Integer)—Specifies the maximum number of results to return. The default is 25; the maximum is 500.

    • StartIndex (System.Integer)—Contains a zero-based index that specifies the first result to return. The default for StartIndex is 0 (the closest entity to the FindNearbySpecification.LatLong unless SortPropeties is specified). In the following example, Count is set to 5 and StartIndex is set to 0, which returns the first five results. To get the next five results, call FindNearby again with StartIndex set to 5. This technique is well-suited for applications with a Next Page feature and reduces the response time of each FindNearby call.

      Microsoft Visual Basic .NET
   Dim myFindRange As New MPNet.FindRange()
   myFindRange.Count = 5   
   myFindRange.StartIndex = 0   

Microsoft Visual C# .NET
   FindRange myFindRange = new FindRange();
   myFindRange.Count = 5;
   myFindRange.StartIndex = 0;

    Note  It is recommended that you always specify the Range.Count property, because returning unused entities increases the response time of your FindNearby query.

  • ResultMask (FindResultMask enumeration), optional
    Restricts the properties of each FindResult.FoundLocation that is returned. The ResultMask property contains values (or combinations of values) from the FindResultMask enumeration. FindResultMask has the following members:

    • FindResultMask.AddressFlag—Populates Location.Address for each FindResult in FindResults.
    • FindResultMask.BestMapViewFlag—Ignored by FindNearby.
    • FindResultMask.EntityFlag—Populates Location.Entity, which contains all of the property names and values for each FindResult in FindResults.
    • FindResultMask.LatLongFlag—Populates Location.LatLong for each FindResult in FindResults.

    The following code example sets the ResultMask property to FindResultMask.EntityFlag and FindResultMask.LatLongFlag using the bitwise Or operator:

    Microsoft Visual Basic .NET
   myFindOptions.ResultMask = _
      FindResultMask.EntityFlag Or FindResultMask.LatLongFlag

Microsoft Visual C# .NET
   myFindOptions.ResultMask = 
      FindResultMask.EntityFlag | FindResultMask.LatLongFlag;

    The default value of ResultMask is the combination of all flags. It is highly recommended that you set ResultMask; otherwise, an excessive amount of data may be transferred, increasing the response time of your FindNearby query.

Examples

We've covered some basic aspects of the FindNearbySpecification class as accepted by FindNearby. Now let's explore how it all fits together to bring a proximity search into your Web site or application.

Calling FindNearby

The following code demonstrates how to call FindNearby. Although Options.ResultMask, Options.Range.Count, and Filter.PropertyNames are optional, they are set here to create a FindNearby query that returns only necessary data and decrease the response time.

Microsoft Visual Basic .NET
   'Declare the variables.
   Dim myFindSpec As New FindNearbySpecification
   Dim myLatLong As New LatLong
   Dim myFindFilter As New FindFilter
   Dim myPropertyNames(4) As String
   Dim myRange As New FindRange
   Dim myFindOptions As New FindOptions
   Dim myFindResults As FindResults

   'Set the properties and objects.

   'Specify the data source.
   myFindSpec.DataSourceName = "MapPoint.FourthCoffeeSample"

   'Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873
   myLatLong.Longitude = -122.131
   myFindSpec.LatLong = myLatLong

   'Set the distance.
   myFindSpec.Distance = 10

   'Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops"

   'Return only the properties that we're interested in.
   myPropertyNames(0) = "Name"
   myPropertyNames(1) = "AddressLine"
   myPropertyNames(2) = "PrimaryCity"
   myPropertyNames(3) = "StoreType"
   myPropertyNames(4) = "Close"
   myFindFilter.PropertyNames = myPropertyNames

   myFindSpec.Filter = myFindFilter

   'Set the Range property.
   myRange.Count = 5
   myFindOptions.Range = myRange

   'Return LatLong and Address information using ResultMask.
   myFindOptions.ResultMask = _
      FindResultMask.LatLongFlag Or FindResultMask.AddressFlag

   myFindSpec.Options = myFindOptions

   'Call FindNearby with a minimum of parameters.

   Try
   myFindResults = myFindService.FindNearby(myFindSpec)
   Catch Err As System.Exception
   MessageBox.Show("An error occurred: " + Err.Message)
   End Try

Microsoft Visual C# .NET
   //Declare the variables.
   FindNearbySpecification myFindSpec = new FindNearbySpecification();
   LatLong myLatLong = new LatLong();
   FindFilter myFindFilter = new FindFilter();
   string[] myPropertyNames = new string[5];
   FindRange myRange = new FindRange();
   FindOptions myFindOptions = new FindOptions();
   FindResults myFindResults;

   //Set the properties and objects.

   //Specify the data source.
   myFindSpec.DataSourceName = "MapPoint.FourthCoffeeSample";

   //Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873;
   myLatLong.Longitude = -122.131;
   myFindSpec.LatLong = myLatLong;

   //Set the distance.
   myFindSpec.Distance = 10;

   //Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops";

   //Return only the properties that we're interested in.
   myPropertyNames[0] = "Name";
   myPropertyNames[1] = "AddressLine";
   myPropertyNames[2] = "PrimaryCity";
   myPropertyNames[3] = "StoreType";
   myPropertyNames[4] = "Close";
   myFindFilter.PropertyNames = myPropertyNames;

   myFindSpec.Filter = myFindFilter;

   //Set the Range property.
   myRange.Count = 5;
   myFindOptions.Range = myRange;

   //Return LatLong and Address information using ResultMask.
   myFindOptions.ResultMask = 
      FindResultMask.LatLongFlag | FindResultMask.AddressFlag;

   myFindSpec.Options = myFindOptions;

   //Call FindNearby with a minimum of parameters.

   try
   {
      myFindResults = myFindService.FindNearby(myFindSpec);
   }
   catch(System.Exception Err)
   {
      MessageBox.Show("An error occurred: " + Err.Message);
   }

Using the WhereClause Property

In this section, we'll create a more complex query by using the WhereClause property. In the following example, only entities with "DeliveryAreas" equal to 98052 and "AcceptsOnlineOrders" equal to true are returned. Note that Options.ResultMask is limited to EntityFlag and LatLongFlag, Filter.PropertyNames is restricted to six properties of interest, and Options.Range.Count is reduced to a value of 5.

Microsoft Visual Basic .NET
   'Declare the variables. 

   Dim myFindSpec As New FindNearbySpecification
   Dim myLatLong As New LatLong
   Dim myFindFilter As New FindFilter
   Dim myPropertyNames(5) As String
   Dim myWhereClause As New WhereClause
   Dim mySearchProperties(1) As EntityPropertyValue
   Dim myFindOptions As New FindOptions
   Dim myRange As New FindRange
   Dim myFindResults As FindResults

   'Set the properties and objects. 

   'Specify the data source.
   myFindSpec.DataSourceName = "MapPoint.FourthCoffeeSample"

   'Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873
   myLatLong.Longitude = -122.131
   myFindSpec.LatLong = myLatLong

   'Specify the distance.
   myFindSpec.Distance = 10

   'Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops"

   'Return only the properties that we're interested in.
   myPropertyNames(0) = "Name"
   myPropertyNames(1) = "AddressLine"
   myPropertyNames(2) = "PrimaryCity"
   myPropertyNames(3) = "Phone"
   myPropertyNames(4) = "StoreType"
   myPropertyNames(5) = "Close"
   myFindFilter.PropertyNames = myPropertyNames

   'Specify the property name/value pairs for which to query.
   mySearchProperties(0) = New EntityPropertyValue
   mySearchProperties(0).Name = "DeliveryAreas"
   mySearchProperties(0).Value = "98052"
   mySearchProperties(1) = New EntityPropertyValue
   mySearchProperties(1).Name = "AcceptsOnlineOrders"
   mySearchProperties(1).Value = True
   myWhereClause.SearchProperties = mySearchProperties

   'Specify And for SearchOperator.
   myWhereClause.SearchOperator = SearchOperatorFlag.And

   'Set Filter.WhereClause.
   myFindFilter.WhereClause = myWhereClause
   myFindSpec.Filter = myFindFilter

   'Set the Range property.
   myRange.StartIndex = 0
   myRange.Count = 5
   myFindOptions.Range = myRange

   'Return LatLong and Entity information using ResultMask.
   myFindOptions.ResultMask = _
      FindResultMask.LatLongFlag Or FindResultMask.EntityFlag

   myFindSpec.Options = myFindOptions

   'Call FindNearby using specified properties.
   Try
      myFindResults = myFindService.FindNearby(myFindSpec)
   Catch Err As System.Exception
      MessageBox.Show("An error occurred: " + Err.Message)
   End Try

Microsoft Visual C# .NET
   //Declare the variables. 

   FindNearbySpecification myFindSpec = new FindNearbySpecification();
   LatLong myLatLong = new LatLong();
   FindFilter myFindFilter = new FindFilter();
   string[] myPropertyNames = new string[6]; 
   WhereClause myWhereClause = new WhereClause();
   EntityPropertyValue[] mySearchProperties = 
      new EntityPropertyValue[2];
   FindOptions myFindOptions = new FindOptions();
   FindRange myRange = new FindRange();
   FindResults myFindResults;

   //Set the properties and objects. 

   //Specify the data source.
   myFindSpec.DataSourceName = "MapPoint.FourthCoffeeSample";

   //Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873;
   myLatLong.Longitude = -122.131;
   myFindSpec.LatLong = myLatLong;

   //Specify the distance.
   myFindSpec.Distance = 50;

   //Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops";

   //Return only the properties that we're interested in.
   myPropertyNames[0] = "Name";
   myPropertyNames[1] = "AddressLine";
   myPropertyNames[2] = "PrimaryCity";
   myPropertyNames[3] = "Phone";
   myPropertyNames[4] = "StoreType";
   myPropertyNames[5] = "Open";
   myFindFilter.PropertyNames = myPropertyNames;

   //Specify the property name/value pairs for which to query.
   mySearchProperties[0] = new EntityPropertyValue();
   mySearchProperties[0].Name = "DeliveryAreas";
   mySearchProperties[0].Value = "98052";
   mySearchProperties[1] = new EntityPropertyValue();
   mySearchProperties[1].Name = "AcceptsOnlineOrders";
   mySearchProperties[1].Value = true;
   myWhereClause.SearchProperties = mySearchProperties;

   //Specify And for SearchOperator.
   myWhereClause.SearchOperator = SearchOperatorFlag.And;

   //Set Filter.WhereClause.
   myFindFilter.WhereClause = myWhereClause;
   myFindSpec.Filter = myFindFilter;

   //Set the Range property.
   myRange.StartIndex = 0;
   myRange.Count = 5;
   myFindOptions.Range = myRange;

   //Return LatLong and Entity information using ResultMask.
   myFindOptions.ResultMask = 
      FindResultMask.LatLongFlag | FindResultMask.EntityFlag;

   myFindSpec.Options = myFindOptions;

   //Call FindNearby using specified properties.

   try
   {
      myFindResults = myFindService.FindNearby(myFindSpec);
   }
   catch(System.Exception Err)
   {
      MessageBox.Show("An error occurred: " + Err.Message);
   }

Using the FilterExpression Property

Filtering using Expression offers more flexibility and complexity than WhereClause. In this example, entities are returned only if they meet all of the following criteria:

  • "StoreType" is either Coffee Shop or Drive-Thru.
  • "Close" is greater than 1900.
  • "AcceptsCoffeeCards" is true.

Again, we limit the properties to ones that we will use, the result count to the limit that we require, and the result mask to an appropriate flag.

Microsoft Visual Basic .NET
   'Declare the variables. 
   Dim myFindSpec As New FindNearbySpecification
   Dim myLatLong As New LatLong
   Dim myFindFilter As New FindFilter
   Dim myPropertyNames(4) As String
   Dim myFilterExpression As New FilterExpression
   Dim myFindOptions As New FindOptions
   Dim myRange As New FindRange
   Dim myFindResults As FindResults

   'Set the properties and objects. 

   'Specify the data source.
   myFindSpec.DataSourceName = "Mappoint.FourthCoffeeSample"

   'Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873
   myLatLong.Longitude = -122.131
   myFindSpec.LatLong = myLatLong

   'Specify the distance.
   myFindSpec.Distance = 10

   'Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops"

   'Return only the properties that we're interested in.
   myPropertyNames(0) = "Name"
   myPropertyNames(1) = "AddressLine"
   myPropertyNames(2) = "PrimaryCity"
   myPropertyNames(3) = "StoreType"
   myPropertyNames(4) = "Close"
   myFindFilter.PropertyNames = myPropertyNames

   'Specify the text of the Expression.
   myFilterExpression.Text = "(StoreType = {0} OR " & _
      "StoreType = {1}) AND Close > {2} AND AcceptsCoffeeCards"

   'Set the paramater values to match the placeholders
   'in the Text string.
   Dim myParameters(2) As Object
   Dim myFirstParameter As String
   myFirstParameter = "Coffee Shop"
   myParameters(0) = myFirstParameter
   Dim mySecondParameter As String
   mySecondParameter = "Drive-Thru"
   myParameters(1) = mySecondParameter
   Dim myThirdParameter As Integer
   myThirdParameter = 1900
   myParameters(2) = myThirdParameter
   myFilterExpression.Parameters = myParameters
   myFindFilter.Expression = myFilterExpression
   myFindSpec.Filter = myFindFilter

   'Set the Range property.
   myRange.StartIndex = 0
   myRange.Count = 10
   myFindOptions.Range = myRange

   'Only return entity information using ResultMask.
   myFindOptions.ResultMask = FindResultMask.EntityFlag

   myFindSpec.Options = myFindOptions

   'Call FindNearby using specified properties.
   Try
      myFindResults = myFindService.FindNearby(myFindSpec)
   Catch Err As System.Exception
      MessageBox.Show("An error occurred: " + Err.Message)
   End Try

Microsoft Visual C# .NET
   //Declare the variables. 
   FindNearbySpecification myFindSpec = new FindNearbySpecification();
   LatLong myLatLong = new LatLong();
   FindFilter myFindFilter = new FindFilter();
   string[] myPropertyNames = new string[5];
   FilterExpression myFilterExpression = new FilterExpression();
   FindOptions myFindOptions = new FindOptions();
   FindRange myRange = new FindRange();
   FindResults myFindResults;

   //Set the properties and objects. 

   //Specify the data source.
   myFindSpec.DataSourceName = "Mappoint.FourthCoffeeSample";

   //Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873; 
   myLatLong.Longitude = -122.131;
   myFindSpec.LatLong = myLatLong;

   //Specify the distance.
   myFindSpec.Distance = 10;

   //Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops";

   //Return only the properties that we're interested in.
   myPropertyNames[0] = "Name";
   myPropertyNames[1] = "AddressLine";
   myPropertyNames[2] = "PrimaryCity";
   myPropertyNames[3] = "StoreType";
   myPropertyNames[4] = "Close";
   myFindFilter.PropertyNames = myPropertyNames;

   //Specify the text of the Expression.
   string myText = "(StoreType = {0} OR StoreType = {1}) AND " +
      "Close > {2} AND AcceptsCoffeeCards";
   myFilterExpression.Text = myText;

   //Set the paramater values to match the placeholders
   //in the Text string.
   object[] myParameters = new object[3];
   string myFirstParameter = "Coffee Shop";
   myParameters[0] = myFirstParameter;
   string mySecondParameter = "Drive-Thru";
   myParameters[1] = mySecondParameter;
   int myThirdParameter = 1900;
   myParameters[2] = myThirdParameter;
   myFilterExpression.Parameters = myParameters;
   myFindFilter.Expression = myFilterExpression;
   myFindSpec.Filter = myFindFilter;

   //Set the Range property.
   myRange.StartIndex = 0;
   myRange.Count = 10;
   myFindOptions.Range = myRange;

   //Only return entity information using ResultMask.
   myFindOptions.ResultMask = FindResultMask.EntityFlag;

   myFindSpec.Options = myFindOptions;

   //Call FindNearby using specified properties.

   try
   {
      myFindResults = myFindService.FindNearby(myFindSpec);
   }
      catch(System.Exception Err)
   {
      MessageBox.Show("An error occurred: " + Err.Message);
   }

Using SortProperties

In this example, we'll use the Expression property to restrict the results to entities whose "AcceptsCoffeeCards" property is false and we'll use the SortProperties property to order the results in ascending order according to the "SeatingCapacity" property.

Note   If an entity has a null "SeatingCapacity," it is included at the end of FindResults. An entity in MapPoint.FourthCoffeeSample contains a non-null value for "SeatingCapacity" only if its "StoreType" is equal to Coffee Shop**.**

Microsoft Visual Basic .NET
   'Declare the variables. 
   Dim myFindSpec As New FindNearbySpecification
   Dim myLatLong As New LatLong
   Dim myFindFilter As New FindFilter
   Dim myPropertyNames(3) As String
   Dim myFilterExpression As New FilterExpression
   Dim mySortProperties(0) As SortProperty
   Dim myFindOptions As New FindOptions
   Dim myRange As New FindRange
   Dim myFindResults As FindResults

   'Set the properties and objects. 

   'Specify the data source.
   myFindSpec.DataSourceName = "Mappoint.FourthCoffeeSample"

   'Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873
   myLatLong.Longitude = -122.131
   myFindSpec.LatLong = myLatLong

   'Specify the distance.
   myFindSpec.Distance = 10

   'Return only the properties that we're interested in.
   myPropertyNames(0) = "Name"
   myPropertyNames(1) = "AddressLine"
   myPropertyNames(2) = "PrimaryCity"
   myPropertyNames(3) = "SeatingCapacity"
   myFindFilter.PropertyNames = myPropertyNames

   'Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops"

   'Set the text of the Expression property.
   'Uses NOT to include values of false.
   myFilterExpression.Text = "NOT(AcceptsCoffeeCards)"

   'Parameters can be null because Text contains no placeholders.
   myFilterExpression.Parameters = Nothing
   myFindFilter.Expression = myFilterExpression

   'Specify the SortProperty property.
   Dim mySortProperty As New SortProperty
   mySortProperty.PropertyName = "SeatingCapacity"
   mySortProperty.Direction = SortDirection.Ascending
   mySortProperties(0) = mySortProperty
   myFindFilter.SortProperties = mySortProperties

   myFindSpec.Filter = myFindFilter

   'Set the Range property.
   myRange.StartIndex = 0
   myRange.Count = 10
   myFindOptions.Range = myRange

   'Return Address and Entity information using ResultMask.
   myFindOptions.ResultMask = _
      FindResultMask.AddressFlag Or FindResultMask.EntityFlag

   myFindSpec.Options = myFindOptions

   'Call FindNearby using specified properties.
   Try
      myFindResults = myFindService.FindNearby(myFindSpec)
   Catch Err As System.Exception
      MessageBox.Show("An error occurred: " + Err.Message)
   End Try

Microsoft Visual C# .NET
   //Declare the variables. 
   FindNearbySpecification myFindSpec = new FindNearbySpecification();
   LatLong myLatLong = new LatLong();
   FindFilter myFindFilter = new FindFilter();
   string[] myPropertyNames = new string[4];
   FilterExpression myFilterExpression = new FilterExpression();
   SortProperty[] mySortProperties = new SortProperty[1];
   FindOptions myFindOptions = new FindOptions();
   FindRange myRange = new FindRange();
   FindResults myFindResults;
   
   //Set the properties and objects. 

   //Specify the data source.
   myFindSpec.DataSourceName = "Mappoint.FourthCoffeeSample";

   //Specify the latitude and longitude.
   myLatLong.Latitude = 47.63873;
   myLatLong.Longitude = -122.131;
   myFindSpec.LatLong = myLatLong;

   //Specify the distance.
   myFindSpec.Distance = 10;

   //Return only the properties that we're interested in.
   myPropertyNames[0] = "Name";
   myPropertyNames[1] = "AddressLine";
   myPropertyNames[2] = "PrimaryCity";
   myPropertyNames[3] = "SeatingCapacity";
   myFindFilter.PropertyNames = myPropertyNames;

   //Set the entity type name to search for.
   myFindFilter.EntityTypeName = "FourthCoffeeShops";
   
   //Set the text of the Expression.
   //Uses NOT to include false values.
   string myText = "NOT(AcceptsCoffeeCards)";
   myFilterExpression.Text = myText;
   
   //Parameters can be null because Text contains no placeholders.
   myFilterExpression.Parameters = null;
   myFindFilter.Expression = myFilterExpression;

   //Specify the SortProperty.
   SortProperty mySortProperty = new SortProperty();
   mySortProperty.PropertyName = "SeatingCapacity";
   mySortProperty.Direction = SortDirection.Ascending;
   mySortProperties[0] = mySortProperty;
   myFindFilter.SortProperties = mySortProperties;
   
   myFindSpec.Filter = myFindFilter;
   
   //Set the Range property.
   myRange.StartIndex = 0;
   myRange.Count = 10;
   myFindOptions.Range = myRange;

   // Return Address and Entity information using ResultMask.
   myFindOptions.ResultMask = 
      FindResultMask.AddressFlag | FindResultMask.EntityFlag;

   myFindSpec.Options = myFindOptions;

   //Call FindNearby using specified properties.

   try
   {
      myFindResults = myFindService.FindNearby(myFindSpec);
   }
   catch(System.Exception Err)
   {
      MessageBox.Show("An error occurred: " + Err.Message);
   }

Conclusion

FindNearby is a powerful method for creating location-aware solutions for your Web site, allowing end-users to find points of interest or your company's nearest location quickly.

When you create spatial queries with FindNearby, you can use the properties of the FindNearbySpecification class to return the results you want. You can:

  • Filter results in two ways, by using the Filter.Expression property or the Filter.WhereClause property.
  • Sort the results by using the Filter.SortProperties property.
  • Include only specific data in the results by using the Filter.PropertyNames and Options.ResultMask properties.

For more information about using custom data with MapPoint Web Service, and for the most current articles, tutorials, and sample applications, visit the MSDN® MapPoint Web site.

Alan Paulin and Frank Morrison are part of the Microsoft MapPoint Business Unit, and are members of the quality assurance team for MapPoint Web Service technologies.