Place Search API
GET Place
Get a list of search results ordered by relevance or distance from a spatial reference point, optionally filtered by category, and optionally bounded within a geographic constraint.
Resource URL
Resource Information
| Response Formats | JSON, XML |
| Authentication | Yes (Requires Key) |
| Rate Limited | Yes |
Request Parameters
| Request Parameter | Description | Required |
|---|---|---|
| location | A geographic context used for searching, ranking, and ordering results. Must consist of two comma-separated floating-point values: the longitude, latitude; the first coordinate must lie in the range [-180, 180], and the second must lie in the range [-90, 90]. Note: 'sort=distance' requires a location; if bounding with a circle/bbox and no location is specified, the center of the circle/bbox will be used by default. | no |
| category | The categories of places to search over. Must consist of a comma-separated list of values, specified with 'sic:' followed by the alphanumeric code. Valid codes include any 'sic' values returned by the Search Ahead API, as well as six-digit North American Industry Classification System (NAICS) codes. | Required if q is not specified. |
| sort | The scheme used to order results. Must be 'distance' or 'relevance'. Note: 'sort=distance' requires a location; if bounding with a circle/bbox and no location is specified, the center of the circle/bbox will be used by default. If a location is detected in the 'q' parameter with 'sort=relevance', the location may influence relevance scoring. 'sort=importance' was available as a sorting option in the initial version of the API, but this option has been deprecated in favor of 'sort=relevance'. 'sort=importance' will be unavailable after 3/31/18; API implementers using 'sort=importance' should migrate to 'sort=relevance'. | yes |
| feedback | If set to true, generated feedback URI templates will be returned in the response. For more information on providing feedback, see the Providing Feedback page. | no |
| key | The API Key, which is needed to make requests to MapQuest services. | yes |
| circle | A geographic circle used to bound the search. Only places within the bound will be returned in results. Must consist of three comma-separated floating-point values: the longitude and latitude of the circle's center, and the radius in meters; the first coordinate must lie in the range [-180, 180], the second must lie in the range [-90, 90], and the radius must lie in the range [0, 800000]. Note: only one of 'circle' and 'bbox' may be specified. | no |
| bbox | A geographic rectangle used to bound the search. Only places within the bound will be returned in results. Must consist of four comma-separated floating-point values: the longitude and latitude of the lower-left corner followed by the longitude and latitude of the upper-right corner; longitudes must lie in the range [-180, 180], and latitudes must lie in the range [-90, 90]. Note: only one of 'circle' and 'bbox' may be specified. | no |
| corridor | A collection of points defining a route used for the search. Must consist of two or more arrays of floating-point longitude, latitude values. Longitudes must lie in the range [-180, 180], and latitudes must lie in the range [-90, 90]. Example: [-120.5,10.1],[-119.4,10.3] Note: Corridor cannot be used with 'location' or 'sort=distance'. | no |
| pageSize | The number of results to return per page. Must lie in the range [1, 50]. Default if unspecified: 10. Note: the starting result number on the requested page must be between 1 and 500, so the maximum allowed value for 'pageSize' could in practice be less than 50, depending on the value of 'page'. | no |
| limit | (Deprecated.) A synonym for 'pageSize', with the same semantics and constraints. If both 'pageSize' and 'limit' are specified, 'pageSize' takes precedence. | no |
| page | The page within the result set to return, where 'pageSize' determines the page size. Must lie in the range [1, 500], and the starting result number on the requested page must be between 1 and 500. Default if unspecified: 1. | no |
| q | A query phrase. Results returned from the Points of Interest dataset will best match the provided query phrase (string) and location (if provided). Examples: 'Starbucks, Denver CO' or 'hotels' | Required if a category is not specified. |
Response Object
| request | A JSON object containing the parameters and values passed in with the request. |
Pagination Object
| currentPage | The current page number of the results returned. |
| nextUrl | A URL that can be used to retrieve the next page of results, if available. |
| previousUrl | A URL that can be used to retrieve the previous page of results, if available. |
Results Object
| displayString | A longer, displayable name for the place, minimally including the name. |
| id | The internal MapQuest id for the place. |
| language | The ISO 639-1 language code for the record. |
| name | A simple name for the place. |
| slug | A path fragment for accessing the item on mapquest.com. |
Place Object
| type | The GeoJSON type of this object. |
Geometry Object
| coordinates | A array of numbers that contains the longitude and latitude that describes the geographic location of the result that is returned. Note: poi results contain a longitude and latitude pair intended to be used for display purposes only. |
| type | A string that represents the type of GeoJSON feature for the result that is returned. Possible values are: Point. |
Properties Object
| type | The type of address entity relevant to this location. Possible values are: address, neighborhood, postalCode, city, county, state, country. |
| street | A string that contains the street address of this location, if applicable to the result returned. |
| city | A string that contains the enclosing city of this location, if applicable to the result returned. |
| state | A string that contains the enclosing state or province of this location, if applicable to the result returned. |
| stateCode | A string that contains the enclosing two-character state code of this location, if applicable to the result returned. |
| county | A string that contains the enclosing county of this location, if applicable to the result returned. |
| country | A string that contains the enclosing country of this location, if applicable to the result returned. |
| countryCode | A string that contains the enclosing ISO 3166-1 Alpha-2 country code of this location, if applicable to the result returned. |
| postalCode | A string that contains the coarsest enclosing postal code, if applicable to the result returned. |
Example Request
cURL Request
curl -X GET -H "Accept: application/json" -H "x-mq-user-id: ABC-123" "https://www.mapquestapi.com/search/v4/place?key=KEY&location=-104.9903,39.7392&sort=relevance&q=restaurants&pageSize=5"
Example Response
JSON
{
"pagination": {
"currentPage": 1
},
"request": {
"sort": "relevance",
"pageSize": 5,
"page": 1,
"feedback": false,
"location": [
-104.9903,
39.7392
],
"q": "restaurants"
},
"results": [
{
"id": "mqId:661957184",
"displayString": "Populus, 240 14th St, Denver, CO 80202",
"name": "Populus",
"slug": "/us/colorado/populus-661957184",
"language": "en",
"place": {
"type": "Feature",
"geometry": {
"coordinates": [
-104.99102,
39.7404
],
"type": "Point"
},
"properties": {
"city": "Denver",
"stateCode": "CO",
"postalCode": "80202",
"county": "",
"countryCode": "US",
"street": "240 14th St",
"type": "address"
}
}
},
{
"id": "mqId:459685272",
"displayString": "Ponti, 100 W 14th Avenue Pkwy, Denver, CO 80204",
"name": "Ponti",
"slug": "/us/colorado/ponti-459685272",
"language": "en",
"place": {
"type": "Feature",
"geometry": {
"coordinates": [
-104.9896,
39.73777
],
"type": "Point"
},
"properties": {
"city": "Denver",
"stateCode": "CO",
"postalCode": "80204",
"county": "",
"countryCode": "US",
"street": "100 W 14th Avenue Pkwy",
"type": "address"
}
}
}
]
}XML
<response>
<pagination>
<currentPage>1</currentPage>
</pagination>
<request>
<sort>relevance</sort>
<pageSize>5</pageSize>
<page>1</page>
<feedback>false</feedback>
<location>
<location>-104.9903</location>
<location>39.7392</location>
</location>
<category/>
<q>restaurants</q>
</request>
<results>
<result>
<id>mqId:661957184</id>
<displayString>Populus, 240 14th St, Denver, CO 80202</displayString>
<name>Populus</name>
<slug>/us/colorado/populus-661957184</slug>
<language>en</language>
<place>
<type>Feature</type>
<geometry>
<coordinates>
<coordinate>-104.99102</coordinate>
<coordinate>39.7404</coordinate>
</coordinates>
<type>Point</type>
</geometry>
<properties>
<city>Denver</city>
<stateCode>CO</stateCode>
<postalCode>80202</postalCode>
<county/>
<countryCode>US</countryCode>
<street>240 14th St</street>
<type>address</type>
</properties>
</place>
</result>
<result>
<id>mqId:459685272</id>
<displayString>Ponti, 100 W 14th Avenue Pkwy, Denver, CO 80204</displayString>
<name>Ponti</name>
<slug>/us/colorado/ponti-459685272</slug>
<language>en</language>
<place>
<type>Feature</type>
<geometry>
<coordinates>
<coordinate>-104.9896</coordinate>
<coordinate>39.73777</coordinate>
</coordinates>
<type>Point</type>
</geometry>
<properties>
<city>Denver</city>
<stateCode>CO</stateCode>
<postalCode>80204</postalCode>
<county/>
<countryCode>US</countryCode>
<street>100 W 14th Avenue Pkwy</street>
<type>address</type>
</properties>
</place>
</result>
</results>
</response>