Search Service Developer's Guide
The Search Service provides a simple interface to get geographic search results. The service can be requested using query parameters, JSON, or XML and can be returned in JSON or XML so it can easily be parsed by client applications. When using the Search Service, there are three main areas to think of: Where do you want to search, how do you want to search, and what sources do you want to search in. Below we will go into more detail on each of these areas.
Hello, World!
Below is a simple example of a search request, although it may look confusing at first, it should be fairly easy to understand after reading this document. In this particular sample, there are only three parameters in the request.
- key - This parameter is common for all of the web services we offer. If you do not know your key or do not have an account with us, visit the Mapquest Developer Network.
- callback - This is not a parameter for the service, just for the Javascript to display 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 sample, there is one latitude/longitude pair.
By default the service assumes it is doing a radius search since it is only given one point. The default area to search is 20 miles away from the center point given. This sample also gives no data to search. By default, if no sources to search are given, it searches our NTPois table of data (data is discussed later in the document).
The JavaScript code which sends the request and displays the result can be viewed here.
(Search will be displayed below)
Contents
Where to Search
When using the Search Service, one of the main parts of the search is where to search. It is possible to search by a point, an area, or along a route.
Points
The above ways of forming areas to search are all made with one or more points. The following are ways of forming points:
- Latitude/Longitude Pair (this format may also be referred to as "raw")
- Address (only works as a point, refer to the Locations documentation on how to properly form addresses)
- IP Address (only works as a point)
- Simple Geo (Refer to Compressed Lat/Lng for more information on this format)
- Compressed Latitude/Longitude Pair (Refer to for more information on this format)
A detailed section about forming different point types can be found in our Forming Points documentation.
Geometry
Using the points above (with the exception of address and ip address), there are multiple ways of forming areas to search. Below is a list of them:
- Polygon - This takes a list of points that should have the same first and last point to complete the polygon shape.
- Line - This is similar to polygon, except it does not end with the starting point. Instead it makes a line (or corridor) that can be searched along. This is mostly used for searching along a route.
For examples and more detailed information, refer to the Geometry documentation.
Bounding Box
One last way of forming a shape can only be used with the Rectangle Search, described later. A bounding box takes two points, an upper rght and lower left, and searches the rectangle those points would create.
There are two parameters for this. One is boundingBox which takes the same type of points Geometry shapes can. Or you can use two locations paramters which can be addresses or IP addresses.
These parameters are discussed in further detail on the Rectangle Search documentation page.
How to Search
To handle the ways of forming search locations, we have multiple search functions to assist searching those types of areas.
Radius Search
This search takes a point formed in any of the formats listed above. It will then search around that point based on the size radius given. For more detailed information, refer to the Radius Search documentation page. Below is an example.
More detailed information can be found at 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 search will take two points, one for the top left corner and one for the bottom right (the points can be formed in any of the above ways and the points do not need to be in the same format). The service will search in the rectangle formed from those two points. For more detailed information, refer to the Rectangle Search documentation page. Below is an example.
More detailed information can be found at 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 search takes multiple points. The polygon search should end with the same point it started with, then the area formed will be searched. For more detailed information, refer to the Polygon Search documentation page. Below is an example.
More detailed information can be found at 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 search takes multiple points, but different from the polygon search, corridor takes a list of points and will search along the line formed. For more detailed information, refer to the Corridor Search documentation page. Below is an example.
Note: This sample demostrates using a compressed format of points.
More detailed information can be found at the Corridor Search documentation.
The JavaScript code which sends the request and displays the result can be viewed here.
(Search will be displayed below)
Base Search
This search is a free-formed search that can handle any of the above searches, although it is missing some of the convenience functionality exposed in the other searches. For more detailed information, refer to the Base Search documentation page. Below is an example.
More detailed information can be found at 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
In the new Search Service, there are even more unit types to use, included drive miles, drive kilometers, drive minutes, and walking minutes. Below is an example to demostrate the new unit types.
The JavaScript code which sends the request and displays the result can be viewed here.
Units:
(Search will be displayed below)
Common Parameters
Each function has unique options, parameters, and returns which are discussed inside each function's documentation page. There are also various parameters which all the search functions use/return. Those can be found in the Common Parameters documentation.
What to Search
After discussing the ways of forming areas to search, there is the issue of what to search. Our search service handles three types of data that can be searched.
Hosted Data
One type of data to search is data hosted by MapQuest. We have mutliple tables of data to search based on the geographic location you are searching and/or what you are searching for. In addition to the tables we host, you can also upload your own data tables that we will host. This can be done by going to the Mapquest Developer Network and signing into your account. Refer to the Hosted Data documentation for more detail. Below is an example using Hosted Data.
More detailed information can be found at the Hosted Data documentation.
The JavaScript code which sends the request and displays the result can be viewed here.
(Search will be displayed below)
Record Info
This function performs more of a lookup on Hosted Data. With this function, you can look up Hosted Data items by Id. For more detailed information, refer to the Record Info documentation page. Below is an example.
More detailed information can be found at the Record Info documentation.
The JavaScript code which sends the request and displays the result can be viewed here.
(Search will be displayed below)
Map Data
In addition to data hosted by us, it is also possible to search data on a map, such as parks, streets, etc. Refer to the Map Data documentation for more detail. Below is an example using Map Data.
More detailed information can be found at the Map Data documentation.
The JavaScript code which sends the request and displays the result can be viewed here.
(Search will be displayed below)
Remote Data
The last type of data to search is remote data. This is user defined points or geometry that is sent in with the request. Refer to the Remote Data documentation for more detail. Below is an example using Remote Data.
More detailed information can be found at 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 search across multiple data sources at once. Below is an example of using all the above sources at once, as well as multiple of the same type of data source.
The JavaScript code which sends the request and displays the result can be viewed here.
(Search will be displayed below)
Paging
Within our Search Service, we provide built in functionality to page the results of a search. Refer to our Paging documentation for details.
Status Codes
All of our searches have different error codes to explain various possible problems. Refer to our Status Codes documentation for details.
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 uses the Mapquest hosted table "MQA.NTPois" for its data source to search.
Notice the extraCriteria part of the hostedData parameter.
This is set specifically to 3016 which is the T value for restaurants. Refer to the NTPois documentation for more T values.
| Options | Value(s) |
|---|---|
| Origin: | |
| Radius: | |
| Max Matches: | |
| Input Format: |
(Output will be displayed below)
Using Your Own Data
The following example demonstrates searching for locations from a data table entered by a user using our Data Manager on the Mapquest Developer Network.
Notice the syntax of the hostedData parameter for guidance on how to configure this for your own data tables.
| Options | Value(s) |
|---|---|
| Max Matches: | |
| Input Format: |
(Output will be displayed below)
Searching the Current Map
The following example demonstrates searching the current map in view. When the map is dragged, it will research the new viewing area. This particular example is using map data and searching for parks in the maps viewing area.
| Options | Value(s) |
|---|---|
| Max Matches: | |
| Input Format: |
(Output will be displayed below)
