Search Service Developer's Guide
For documentation on v1 of the Search Service, please visit the Search Service v1 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. Default is 100.
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 NAVTEQ 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.
Differences between Search API v1 and v2
There are a few differences between the previous version of the Search API and the current version:
- Data stored in the previous version of the MapQuest Data Manager (accessible through the "Manage AppKeys" screen on the MapQuest Developer Network) is not accessible to the Search API v2. Data in the previous version of Data Manager must be re-uploaded through the Data Manager API.
- Tables uploaded through the Data Manager API have a prefix of mqap instead of the MQA. For instance, the NAVTEQ North American Points of Interest table is now mqap.ntpois instead of MQA.NTPois.
- Map Data Search is not available in the Search API v2.
Types of searching
Note: All examples are searching and displaying results from the MapQuest-hosted NAVTEQ POI data table. While the examples use the MapQuest-hosted NAVTEQ 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 |
|---|---|
| 0 | A successful search call. |
| 400 | Error with input - The error message will start with: "Illegal argument from request:" followed by the specific error condition. |
| 403 | Key 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. |
| 500 | Unknown 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)
