Search API
POST Radius Search
The Radius Search service allows a search of a data set to be made by entering the latitude/longitude pair or by giving a single-line origin address.
Resource URL
Resource Information
| Response Formats | JSON, XML |
| Authentication | Yes (Requires Key) |
| Rate Limited | Yes |
URL Parameters
| URL Parameter | Description | Required |
|---|---|---|
| key | The API Key, which is needed to make requests to MapQuest services. | Yes |
| inFormat | Specifies the format of the request body. Must be one of the following, if supplied:
json if not supplied | No |
| outFormat | Specifies the format of the response. Must be one of the following, if supplied:
json if not supplied | No |
| ambiguities String | Use this parameter to set the strategy for resolving ambiguous location names. If this parameter is set to ignore, the Search Service will simply use the first location found for an address.If this parameter is not set, or set to a value other than ignore, the Search Service will return a full list of the possible location matches in the collections attribute of the response. | No |
| callback | A JavaScript function name. The JSON-formatted response will be wrapped in a call to the supplied callback function name to provide JSONP functionality. This functionality might be needed to do cross-site scripting. See the Wikipedia.org entry for JSON for more details. | No |
Body Parameters
| Body Parameters | Description | Required |
|---|---|---|
| origin Location | This is the origin location of the request. A valid origin can be any kind of single-line address. In order to use compressed or simple formatted latitude/longitude pairs, refer to the Base Search documentation. | Yes |
| hostedDataList List of Hosted Data Objects | HostedData objects will contain data hosted by MapQuest. This includes tables of points of interest from around the world, as well as allowing users to upload data to our servers for it to be stored. This parameter allows you to query these data sets as part of your search request. Refer to the Hosted Data page for more information. | No |
| remoteDataList List of RemoteData Objects | RemoteData objects contain data provided by the user as part of the request that will be included in the search. Refer to the Remote Data page for more information. | No |
Body Options Parameters
| Options Parameters | Description | Required |
|---|---|---|
| radius Double | Distance from the origin to search. The units for this parameter are set by the units parameter. | No |
| units String | Specifies the type of units to use when calculating distance. Search results are then ordered by distance from lowest to highest. Notice there are some additional parameters here than in our other services. Acceptable values are:
m | No |
| shapeFormat String | These shapeFormats are also described in more detail on the Geometry page. Shape format options:
See the Simple Features Wiki description page for more detail. | No |
| maxMatches Integer | 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. | No |
| pageSize Integer | The number of results per page. If a value is not assigned to this parameter, by default, all of the results will be displayed on one page. | No |
| currentPage Integer | This value indicates a specific page of the displayed results. The default value is 1. For example, if the pageSize is set to 5 (5 results per page) and the current page is set to 2 (the second page of results), result numbers 6-10 would be returned. | No |
Response
Radius Search Response Fields
| Response Field | Description |
|---|---|
| origin Location | This is the origin of the search radius |
| radius Double | Distance from the origin searched. |
Search Response Fields
| Response Field | Description |
|---|---|
| info | This field contains information about the response. The statusCode subfield is an integer return value. Refer to the status codes page for more details on our status codes and error messages. The messages subfield is an array of error messages which describe the status. |
| ambiguities Boolean | This will return true or false if ambiguities could be returned. |
| units String | Specifies the type of units to use when calculating distance. Acceptable values are:
"m" |
| maxMatches Integer | Maximum amount of results to return. |
| shapeFormat String | Shape format of all shapePoints returned
See the Simple Features Wiki description page for more detail. |
| currentPage Integer | The current page of results. |
| pageSize Integer | If a page size was set on the request, this is the number of results to return per page in the request. |
| remoteData RemoteData | A list of remote data to search against |
| hostedData HostedData | A list of hosted data sources to search against |
| resultsCount Integer | The number of total results found, this includes the cached paged items. |
| searchResult SearchResult | The results of the search request. Refer below to the SearchResult object documentation for details. |
Example Request
Example Request Body
JSON
{
"origin": {
"latLng": {
"lat": 39.750307,
"lng": -104.999472
}
},
"options": {
"maxMatches": 4
}
}XML
<search>
<origin>
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</origin>
<options>
<maxMatches>4</maxMatches>
</options>
</search>Example Response
JSON
{
"searchResults": [
{
"resultNumber": 1,
"distance": 0,
"sourceName": "mqap.ntpois",
"name": "Cholon",
"shapePoints": [
39.750307,
-104.999472
],
"distanceUnit": "m",
"key": "6318dd07-b366-4d80-b82a-88b5b456b929",
"fields": {
"phone": "+(1)-(720)-5368609",
"side_of_street": "N",
"group_sic_code": "581208",
"state": "CO",
"lng": -104.999472,
"group_sic_code_name": "(All) Restaurants",
"city": "Denver",
"country": "US",
"group_sic_code_name_ext": "(All) Restaurants",
"id": "270729839",
"mqap_geography": {
"latLng": {
"lng": -104.999472,
"lat": 39.750307
}
},
"address": "1555 Blake St",
"postal_code": "80202",
"name": "Cholon",
"mqap_id": "6318dd07-b366-4d80-b82a-88b5b456b929",
"group_sic_code_ext": "581208",
"disp_lat": 39.750307,
"lat": 39.750307,
"disp_lng": -104.999472
}
},
{
"resultNumber": 2,
"distance": 0,
"sourceName": "mqap.ntpois",
"name": "Sugar Cube Building",
"shapePoints": [
39.750307,
-104.999472
],
"distanceUnit": "m",
"key": "29202c14-9a24-4d5f-9075-ae489e8af441",
"fields": {
"phone": "+(1)-(720)-9040928",
"side_of_street": "N",
"group_sic_code": "653118",
"state": "CO",
"lng": -104.999472,
"group_sic_code_name": "Real Estate Agents",
"city": "Denver",
"country": "US",
"group_sic_code_name_ext": "Real Estate Agents",
"id": "345964805",
"mqap_geography": {
"latLng": {
"lng": -104.999472,
"lat": 39.750307
}
},
"address": "1555 Blake St",
"postal_code": "80202",
"name": "Sugar Cube Building",
"mqap_id": "29202c14-9a24-4d5f-9075-ae489e8af441",
"group_sic_code_ext": "653118",
"disp_lat": 39.750307,
"lat": 39.750307,
"disp_lng": -104.999472
}
},
{
"resultNumber": 3,
"distance": 0,
"sourceName": "mqap.ntpois",
"name": "Dealer Group",
"shapePoints": [
39.750307,
-104.999472
],
"distanceUnit": "m",
"key": "4c6967df-f843-4da8-acc6-8fcde91da82d",
"fields": {
"phone": "+(1)-(720)-9040440",
"side_of_street": "N",
"group_sic_code": "551102",
"state": "CO",
"lng": -104.999472,
"group_sic_code_name": "(All) Auto Dealers",
"city": "Denver",
"country": "US",
"group_sic_code_name_ext": "(All) Auto Dealers",
"id": "279569749",
"mqap_geography": {
"latLng": {
"lng": -104.999472,
"lat": 39.750307
}
},
"address": "1555 Blake St",
"postal_code": "80202",
"name": "Dealer Group",
"mqap_id": "4c6967df-f843-4da8-acc6-8fcde91da82d",
"group_sic_code_ext": "551102",
"disp_lat": 39.750307,
"lat": 39.750307,
"disp_lng": -104.999472
}
},
{
"resultNumber": 4,
"distance": 0,
"sourceName": "mqap.ntpois",
"name": "Urban Villages",
"shapePoints": [
39.750307,
-104.999472
],
"distanceUnit": "m",
"key": "a463baab-a449-40ed-adcb-62dd63cc9b30",
"fields": {
"phone": "+(1)-(720)-9040928",
"side_of_street": "N",
"group_sic_code": "152130",
"state": "CO",
"lng": -104.999472,
"group_sic_code_name": "Construction Building Contractors",
"city": "Denver",
"country": "US",
"group_sic_code_name_ext": "Construction Building Contractors",
"id": "279165586",
"mqap_geography": {
"latLng": {
"lng": -104.999472,
"lat": 39.750307
}
},
"address": "1555 Blake St",
"postal_code": "80202",
"name": "Urban Villages",
"mqap_id": "a463baab-a449-40ed-adcb-62dd63cc9b30",
"group_sic_code_ext": "152130",
"disp_lat": 39.750307,
"lat": 39.750307,
"disp_lng": -104.999472
}
}
],
"origin": {
"latLng": {
"lng": -104.999472,
"lat": 39.750307
},
"adminArea4": "",
"adminArea5Type": "City",
"adminArea4Type": "County",
"adminArea5": "",
"street": "",
"adminArea1": "",
"adminArea3": "",
"type": "s",
"displayLatLng": {
"lng": -104.999472,
"lat": 39.750307
},
"linkId": 0,
"postalCode": "",
"sideOfStreet": "N",
"dragPoint": false,
"adminArea1Type": "Country",
"geocodeQuality": "LATLNG",
"geocodeQualityCode": "XXXXX",
"adminArea3Type": "State"
},
"resultsCount": 4,
"hostedData": [
{
"tableName": "mqap.ntpois",
"extraCriteria": "",
"columnNames": []
}
],
"totalPages": 1,
"info": {
"statusCode": 0,
"copyright": {
"text": "© 2023 MapQuest, Inc.",
"imageUrl": "https://api.mqcdn.com/res/mqlogo.gif",
"imageAltText": "© 2023 MapQuest, Inc."
},
"messages": []
},
"options": {
"kmlStyleUrl": "http://www.search.mapquestapi.com/kml-default.kml",
"shapeFormat": "raw",
"ambiguities": true,
"pageSize": 4,
"radius": 20,
"currentPage": 1,
"units": "m",
"maxMatches": 4
}
}XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<info>
<statusCode>0</statusCode>
<messages/>
<copyright>
<imageUrl>https://api.mqcdn.com/res/mqlogo.gif</imageUrl>
<imageAltText>© 2023 MapQuest, Inc.</imageAltText>
<text>© 2023 MapQuest, Inc.</text>
</copyright>
</info>
<search>
<options>
<maxMatches>4</maxMatches>
<units>m</units>
<shapeFormat>raw</shapeFormat>
<kmlStyleUrl>http://www.search.mapquestapi.com/kml-default.kml</kmlStyleUrl>
<currentPage>1</currentPage>
<pageSize>4</pageSize>
<ambiguities>true</ambiguities>
<radius>20.0</radius>
</options>
<resultsCount>4</resultsCount>
<totalPages>1</totalPages>
<hostedDataList>
<hostedData>
<tableName>mqap.ntpois</tableName>
<columnNames/>
</hostedData>
</hostedDataList>
<searchResults>
<searchResult>
<key>6318dd07-b366-4d80-b82a-88b5b456b929</key>
<name>Cholon</name>
<resultNumber>1</resultNumber>
<distance>0.0</distance>
<distanceUnit>m</distanceUnit>
<sourceName>mqap.ntpois</sourceName>
<shapePoints type="point">
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</shapePoints>
<fields>
<phone>+(1)-(720)-5368609</phone>
<side_of_street>N</side_of_street>
<group_sic_code>581208</group_sic_code>
<state>CO</state>
<lng>-104.999472</lng>
<group_sic_code_name>(All) Restaurants</group_sic_code_name>
<city>Denver</city>
<country>US</country>
<group_sic_code_name_ext>(All) Restaurants</group_sic_code_name_ext>
<id>270729839</id>
<mqap_geography>POINT (-104.999472 39.750307)</mqap_geography>
<address>1555 Blake St</address>
<group_sic_code_ext>581208</group_sic_code_ext>
<mqap_id>6318dd07-b366-4d80-b82a-88b5b456b929</mqap_id>
<name>Cholon</name>
<postal_code>80202</postal_code>
<disp_lat>39.750307</disp_lat>
<lat>39.750307</lat>
<disp_lng>-104.999472</disp_lng>
</fields>
</searchResult>
<searchResult>
<key>29202c14-9a24-4d5f-9075-ae489e8af441</key>
<name>Sugar Cube Building</name>
<resultNumber>2</resultNumber>
<distance>0.0</distance>
<distanceUnit>m</distanceUnit>
<sourceName>mqap.ntpois</sourceName>
<shapePoints type="point">
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</shapePoints>
<fields>
<phone>+(1)-(720)-9040928</phone>
<side_of_street>N</side_of_street>
<group_sic_code>653118</group_sic_code>
<state>CO</state>
<lng>-104.999472</lng>
<group_sic_code_name>Real Estate Agents</group_sic_code_name>
<city>Denver</city>
<country>US</country>
<group_sic_code_name_ext>Real Estate Agents</group_sic_code_name_ext>
<id>345964805</id>
<mqap_geography>POINT (-104.999472 39.750307)</mqap_geography>
<address>1555 Blake St</address>
<group_sic_code_ext>653118</group_sic_code_ext>
<mqap_id>29202c14-9a24-4d5f-9075-ae489e8af441</mqap_id>
<name>Sugar Cube Building</name>
<postal_code>80202</postal_code>
<disp_lat>39.750307</disp_lat>
<lat>39.750307</lat>
<disp_lng>-104.999472</disp_lng>
</fields>
</searchResult>
<searchResult>
<key>4c6967df-f843-4da8-acc6-8fcde91da82d</key>
<name>Dealer Group</name>
<resultNumber>3</resultNumber>
<distance>0.0</distance>
<distanceUnit>m</distanceUnit>
<sourceName>mqap.ntpois</sourceName>
<shapePoints type="point">
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</shapePoints>
<fields>
<phone>+(1)-(720)-9040440</phone>
<side_of_street>N</side_of_street>
<group_sic_code>551102</group_sic_code>
<state>CO</state>
<lng>-104.999472</lng>
<group_sic_code_name>(All) Auto Dealers</group_sic_code_name>
<city>Denver</city>
<country>US</country>
<group_sic_code_name_ext>(All) Auto Dealers</group_sic_code_name_ext>
<id>279569749</id>
<mqap_geography>POINT (-104.999472 39.750307)</mqap_geography>
<address>1555 Blake St</address>
<group_sic_code_ext>551102</group_sic_code_ext>
<mqap_id>4c6967df-f843-4da8-acc6-8fcde91da82d</mqap_id>
<name>Dealer Group</name>
<postal_code>80202</postal_code>
<disp_lat>39.750307</disp_lat>
<lat>39.750307</lat>
<disp_lng>-104.999472</disp_lng>
</fields>
</searchResult>
<searchResult>
<key>a463baab-a449-40ed-adcb-62dd63cc9b30</key>
<name>Urban Villages</name>
<resultNumber>4</resultNumber>
<distance>0.0</distance>
<distanceUnit>m</distanceUnit>
<sourceName>mqap.ntpois</sourceName>
<shapePoints type="point">
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</shapePoints>
<fields>
<phone>+(1)-(720)-9040928</phone>
<side_of_street>N</side_of_street>
<group_sic_code>152130</group_sic_code>
<state>CO</state>
<lng>-104.999472</lng>
<group_sic_code_name>Construction Building Contractors</group_sic_code_name>
<city>Denver</city>
<country>US</country>
<group_sic_code_name_ext>Construction Building Contractors</group_sic_code_name_ext>
<id>279165586</id>
<mqap_geography>POINT (-104.999472 39.750307)</mqap_geography>
<address>1555 Blake St</address>
<group_sic_code_ext>152130</group_sic_code_ext>
<mqap_id>a463baab-a449-40ed-adcb-62dd63cc9b30</mqap_id>
<name>Urban Villages</name>
<postal_code>80202</postal_code>
<disp_lat>39.750307</disp_lat>
<lat>39.750307</lat>
<disp_lng>-104.999472</disp_lng>
</fields>
</searchResult>
</searchResults>
<origin>
<geocodeQuality>LATLNG</geocodeQuality>
<geocodeQualityCode>XXXXX</geocodeQualityCode>
<dragPoint>false</dragPoint>
<sideOfStreet>N</sideOfStreet>
<displayLatLng>
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</displayLatLng>
<linkId>0</linkId>
<type>s</type>
<latLng>
<lat>39.750307</lat>
<lng>-104.999472</lng>
</latLng>
</origin>
</search>
</response>