Place Search API V5 beta
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. V5 provides enhanced international search capabilities.
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 |
| 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 |
| limit | The number of results to return. Must lie in the range [1, 100]. Default if unspecified: 20. | 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. |
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. |
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. |
| 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. |
| sic | An array of objects containing Standard Industrial Classification (SIC) codes for the place, providing category information for the result. Each object contains id (string) and name (string) properties. |
Example Request
cURL Request
curl -X GET -H "Accept: application/json" "https://www.mapquestapi.com/search/v5/place?key=KEY&location=-104.9903,39.7392&sort=relevance&q=restaurants&limit=5"
Example Response
JSON
{
"request": {
"sort": "relevance",
"limit": 5,
"location": [
-104.9903,
39.7392
],
"q": "restaurants"
},
"results": [
{
"id": "cGRzOnBsYWNlOjg0MDl4ajY0LThkYjkxZTNlNTRjYmNjODhiYWVjNzBjZGU0M2YxYWYy",
"displayString": "Populus, 240 14th St, Denver, CO 80202",
"name": "Populus",
"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",
"sic": [
{
"id": "SIC:5812",
"name": "Restaurant"
},
{
"id": "SIC:58120302",
"name": "Take Out and Delivery Only"
},
{
"id": "SIC:58120300",
"name": "Fast Food"
}
]
}
}
},
{
"id": "cGRzOnBsYWNlOjg0MDl4ajY0LWI0M2UzMDU5NmMzOTRkZWNhMjJmZmRlMmQ5ZDZjZDg4",
"displayString": "Ponti, 100 W 14th Avenue Pkwy, Denver, CO 80204",
"name": "Ponti",
"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",
"sic": [
{
"id": "SIC:5812",
"name": "Restaurant"
}
]
}
}
}
]
}XML
<response>
<request>
<sort>relevance</sort>
<limit>5</limit>
<location>
<location>-104.9903</location>
<location>39.7392</location>
</location>
<category/>
<q>restaurants</q>
</request>
<results>
<r>
<id>cGRzOnBsYWNlOjg0MDl4ajY0LThkYjkxZTNlNTRjYmNjODhiYWVjNzBjZGU0M2YxYWYy</id>
<displayString>Populus, 240 14th St, Denver, CO 80202</displayString>
<n>Populus</n>
<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>
<sic>
<item>
<id>SIC:5812</id>
<name>Restaurant</name>
</item>
<item>
<id>SIC:58120302</id>
<name>Take Out and Delivery Only</name>
</item>
<item>
<id>SIC:58120300</id>
<name>Fast Food</name>
</item>
</sic>
</properties>
</place>
</r>
<r>
<id>cGRzOnBsYWNlOjg0MDl4ajY0LWI0M2UzMDU5NmMzOTRkZWNhMjJmZmRlMmQ5ZDZjZDg4</id>
<displayString>Ponti, 100 W 14th Avenue Pkwy, Denver, CO 80204</displayString>
<n>Ponti</n>
<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>
<sic>
<item>
<id>SIC:5812</id>
<name>Restaurant</name>
</item>
</sic>
</properties>
</place>
</r>
</results>
</response>