DoSearch2 method


RestSearchResults DoSearch2(int ClientId, string ApiKey,
    string PostalCode, string City, string State,
    int CountryId,
    string CategoryIds, int Radius,
    string Latitude, string Longitude,
    string Keyword,
    string UserIPAddress,
    bool ReturnGeocode, bool FillAttr,
    bool ReturnCoupon, string SearchSourceName,
    int StartIndex, int PageSize,
    int SearchTypeOverride, string CountryScope,
    int MaxResults, bool MatchAllCategories,
    bool ReturnServices, bool FindNearestForNoResults,
    bool GetHoursForUpcomingWeek, string LanguageCode,
    int LanguageID)

End Point:


This method will return a list of locations, given search criteria. This call wraps the returned list in a structure that includes the total number of results.

Specify postal code (5-digit zip), city and state (2-alpha state code), or latitude/longitude (degrees). If you specify a lat/lon pair, a radius search will be performed.  If you specify postal code or city/state, your configured search type (territory or radius) will be used.

If you specify a keyword, this will be used to filter results to locations containing that keyword in the name field.

If you specify a user IP address, then this will be checked against the list of blocked IP addresses for this client.  If the address is on the block list, the search will not be performed, and a 403 (forbidden) response code will be returned. Passing this argument also causes the given IP address to be logged, if search logging is enabled for this client. (If the user IP is not passed in, then the IP of the machine calling the web service will be logged.)

You can specify a comma-delimited list of categories, to limit your search to those categories.

Specify radius in miles. To perform a literal search unconstrained by radius, pass -1 as the radius. This will allow you to retrieve all locations in a given postal code, state, or city/state, or matching a given keyword.

Results should be retrieved one page at a time.  To retrieve the first 25 results, specify StartIndex = 0 and PageSize = 25.  To retrieve the next 25 results, specify StartIndex=25, PageSize=25.

CountryId should be set to 1 for US and 2 for Canada.  For other country codes, you can check the result of the GetCountryList method.  You can also check our Country Codes article.

If the FillAttr parameter is set to true, the web service will fill in the Attributes list in each  location result.  If not, then the attributes list will not be filled in. (In some instances, returning attributes can slow down the search. Do not return attributes unless you need them.)

If the ReturnCoupon parameter is set to true, the web service will fill in the Coupons list in each  location result.  If not, then the coupons list will not be filled in.

The SearchSourceName parameter can be used to indicate the source of this search, for reporting purposes. Default source names are “Web” and “Facebook”. To use another name, you must set it up via the Bullseye admin site.

The optional parameter SearchTypeOverride can be used to change the inherent search type for a particular country.  The inherent Search Type refers to the Search Rules configured for a country on the Bullseye admin site.  For example, if the search type for Australia is set to Radius Search, setting the SearchTypeOverride to the value for Country Search will result in all Australian locations being returned. The defined search types are:

  • Radius: 1 - Retrieves all locations that fall within the distance defined by the Radius parameter. For the US, the value of the Radius parameter is interpreted in miles; in all other countries it is considered kilometers. A starting point needs to be defined through a combination of the City, State, PostalCode, Latitude and Longitude parameters.
  • Territory: 2 - Based on the inputted starting point, retrieves all locations that belong to defined territories that include the starting point.
  • Literal: 3 - Retrieves all locations within a country that have the value in the Keyword parameter in their name.
  • Country: 4 - Retrieves all locations that fall within the country defined by the CountryId parameter.

An example of when to use the SearchTypeOverride parameter is if no results are returned for a country configured for Radius Search. The fallback for that situation would be to have a second call with SearchTypeOverride set to Country that would return all locations for that country.

The optional parameter CountryScope is used to access all locations regardless of what country they are in.  It must be used in conjunction with the SearchTypeOverride parameter being set to Country Search.  It also requires that the Other International subscription has been set up through the Bullseye admin site, as it uses the search and sort rules associated with this subscription.   For now this parameter only has one acceptable value, "All", which will return all locations worldwide. The locations can be filtered by Category and Keyword if those parameters have been provided.

Another optional parameter is MaxResults, which can be used to set a ceiling on the number of results returned if this has not been set for a specific country, or to override that setting if it exists for the country that is being searched.

An additional optional parameter has been added to return the services that a location is assigned to, called ReturnServices. When set to "True", this parameter results in two flags on the Location object being set for each location: IsStoreLocator and IsLeadManager.  If not set, or set to false, these fields will not be populated and should be ignored.

For search requests which require locations to match all of the categories input, the MatchAllCategories optional parameter can be used. This parameter is automatically set to false, but when overridden to true will require that any result be assigned to all categories passed in.

If an optional parameter FindNearestForNoResults is set to true, the web service will return the single nearest result when no results are found for the specified search radius within the country being searched.

If location data needs to be translated into another language and the account has location translations enabled, one of two optional parameters can be specified: LanguageCode and LanguageID. LanguageCode requires the ISO code for the language desired: LanguageID refers to the internal Bullseye ID for a language.

For displaying the hours for the upcoming week for returned locations, the optional GetHoursForUpcomingWeek parameter should be set to True. This will result in the DailyHoursList section of each location being filled in.

	var mydata = {
	  ClientId: 999,
	  ApiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	  //PostalCode: "08876",
	  City: "Somerset", State: "NJ", CountryId: 1,
	  //Latitude: 40.54374, Longitude: -74.66004,
	  //UserIPAddress: "",
	  //SearchTypeOverride: 1, CountryScope: "All", MaxResults: 25, 
	  ReturnGeocode: true,
	  //FillAttr: true, ReturnCoupon: false,
	  //MatchAllCategories: true,
	  //GetHoursForUpcomingWeek: false, LanguageCode: "en",
	  CategoryIds: "1,2,3",
	  //SearchSourceName: "Catalog",
	  //Keyword: "Davidson",
	  Radius: 5,
	  StartIndex: 0, PageSize: 25
	$.ajax( {
	  url: "",
	  data: mydata,
	  type: "GET",
	  processData: true,
	  timeout: 10000,
	  dataType: "json",
		function(data, status, xhr) {
			$("div#results").text(data.TotalResults + 
			  " total results. " + 
			  data.ResultList.length + 
			  " elements returned in ResultList.");
		} ,
		function(xhr, status, ex) {
			console.log("ERROR: "+status);
	} );