Search Service Developer's Guide

The MapQuest Search API provides a simple interface for performing spatial searches on hosted and remote data. You can use the Search API to answer questions such as 'Which coffee shops are within a 5-minute drive from my house?' or 'Which data points fall within a particular ZIP code?' The Search API supports the following major search functions: radius, rectangle, polygon and corridor, and includes the ability to search data hosted by MapQuest as well as remote data that is passed in with the search request.

Hello, World!

Below is a simple example of a search request. In this particular sample, there are only four parameters in the request:

  • key - This parameter is common to all of the MapQuest APIs. If you do not have an AppKey, visit the MapQuest Developer Network and create an account.
  • callback - This is not a parameter needed for the service. Instead, it is a callback specific to this example, to show the results below.
  • shapePoints - You will see further in the documentation that there are multiple ways of forming a value for this parameter. In this example, there is one latitude/longitude pair.
  • maxMatches - This is the number of results returned in the response. While the limit for the maximum number of results returned is 500, the default value is 100 for all types of Search requests.

By default, the service assumes it is doing a radius search since it is only given one point. The default radius is 20 miles from the point passed into the request. Also, by default, the Search API will perform a hosted data search on the North American Points of Interest table (mqap.ntpois) table of data if no data source is specified in the request.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Contents

Getting started

Base URL

This is the base URL needed to make a request to the Search API.

Common parameters

Each type of search request offers unique options, parameters, and results; however, there are also parameters that are common to each type of search request. Parameters such as those that define the input and output formats, number of results to return, and search units can be defined in all types of search requests.

Types of searching

Note: All examples are searching and displaying results from the MapQuest-hosted POI data table. While the examples use the MapQuest-hosted POI data table, other types of data can be used with Search API functions as well, including your own custom data stored in Data Manager tables or remote data passed in with the search request.

Radius search

This type of search returns results that are within a given distance of an origin. An origin can be defined as latitude and longitude coordinates, a street address, or even an IP address, while a radius can be defined in terms of units and size. Radius searching is further explained in the radius search documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Rectangle search

This type of search will return results that are within a specific bounding box (rectangle). The rectangle is formed by defining upper left and lower right points. Rectangle searching is further explained in the rectangle search documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Polygon search

This type of search will return results that are within a custom polygon shape. The polygon is defined by a series of points (coordinates) that end with the same point it started with. Polygon searching is further explained in the polygon search documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Corridor search

This type of search will return results that fall within a specified distance of a line; for instance, a corridor search could return results that are within a specified distance of a route. The line (corridor) is formed by a series of points. Corridor searching is further explained in the corridor search documentation. Note: This sample demonstrates using a compressed format of points, but a corridor search request will accept points in other formats as well.

The JavaScript code which sends the request and displays the result can be viewed here

(Search will be displayed below)     

Base search

This type of search is a free-form search that can handle any of the above searches, although it is missing some of the convenience functionality exposed in the other searches. The base search functionality is further explained in the base search documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Driving/walking time search

The Search API will return results ordered by drive miles, drive kilometers, drive minutes, and walking minutes. The unit type can be set by defining the units parameter in a search request. Search results will default to miles if the units parameter is not defined.

The JavaScript code which sends the request and displays the result can be viewed here.

Units: 

(Search will be displayed below)     

Record info search

This function performs a lookup on hosted data items by specific record ID. Record info searching is further explained in the record info documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Types of data to search

Now that we've talked about the types of searching available with the Search API, let's talk about data that can be searched.

Hosted data

The MapQuest Data Manager is essentially a large database hosted by MapQuest. MapQuest hosts multiple data tables that are available to search through the Search API. In addition to the MapQuest-hosted tables, you can also upload your own data to Data Manager, and we'll host the data for you. Refer to the Hosted Data documentation for more detail about how to search Data Manager tables. Below is an example using Hosted Data.

Note: Data must be uploaded through the Data Manager API in order to be accessible by the Search API. Data tables in the previous version of Data Manager (tables that have an MQA prefix instead of mqap) are not accessible by the Search API v2.

More detailed information can be found on the Hosted Data documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Remote data

Remote data simply refers to user-defined points or geometry that is sent in with a search request. Refer to the Remote Data documentation for more detail. Remote data is further explained in the remote data documentation.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Mixing data sources

It is also possible to mix data sources when using the Search API. The following example uses all of the previously mentioned data sources together in one request.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     

Search results

Filtering

See the hosted data search documentation for information about how to query and filter search results based on various criteria.

Paging

The Search API offers paging functionality; meaning, search results can be requested and returned in a page-by-page manner. For instance, if there are 50 results total, but you want to display 10 results at a time, results would be divided into 5 pages with 10 results on each page. Each page of results can be requested and returned from the Search API. Paging is further explained in the paging documentation.

Status codes

Status codes are returned for all Search API functions and are especially helpful when troubleshooting errors. A more detailed list of status codes specific to each Search API function are available in the status codes documentation.

Status Code Description
0A successful search call.
400Error with input - The error message will start with: "Illegal argument from request:" followed by the specific error condition.
403Key related error - The error message will attempt to explain why there was an error with the key and should provide a link to the Developer Network.
500Unknown error - The error message will start with: "Error processing request:" followed by the message from the exception.
601 A Search's internal geocode is invalid for some reason, probably an incorrect location has been passed
602 A Search's internal geocode failed, most likely the address doesn't exist
603 A Search's internal routing failed, most likely an invalid location or internal error
609 No search data was provided, please supply a Map, Hosted, or Remote data object to search
610 A Search generated an ambigious geocode result, more that one possible result has been found for your address

More examples

Locating a restaurant

The following example demonstrates for to find a restaurant using a radius search. This will allow a user to look for a specific restaurant or locate any restaurant within the given radius. It searches the MapQuest-hosted "mqap.ntpois" table. Notice the extraCriteria part of the hostedData parameter. This is set specifically to 581208 which is the group_sic_code value for restaurants. Refer to the NTPois documentation for more group_sic_code values.


Options Value(s)
Origin:
Radius:
Max Matches:
Input Format:

 (Output will be displayed below)

  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use