Search API

POST
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.

Resource URL

https://www.mapquestapi.com/search/v2/corridor

Resource Information

Response Formats JSON, XML
Authentication Yes (Requires Key)
Rate Limited Yes

URL Parameters

Request 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
  • xml
Default = json
No
outFormat

Specifies the format of the response. Must be one of the following, if supplied:

  • json
  • xml
  • csv (character delimited)

Defaults to "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 Parameter Description Required?
sessionId
String

Using our Directions Web Service, it is possible to use the session Id from a previous route, then do a corridor search along that route.

Yes - This is a required parameter if the line parameter is not supplied!
line
LineString
The LineString of points to search along. Yes - This is a required parameter if the sessionId parameter is not supplied!
width
Number
The width of how far away from the corridor path to search.

If provided, the units parameter will be used for measurement. Otherwise, the width will default to miles.

Default is 5.
No
bufferedWidth
Number
The bufferedWidth is used if the maximum number of results has not been reached within the given width. It will then use the bufferedWidth to add to the width to try and get more results.

If provided, the units parameter will be used for measurement. Otherwise, the width will default to miles.

Default is 0.25.
No
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

Body Parameters Description Required?
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 - Miles - Sorts the results by straight line distance in miles (straight line distance).
  • k - Kilometers - Sorts the results by straight line distance in kilometers (straight line distance).
  • wmin - Walking Minutes - Sorts the results by shortest walking time (calculated as an actual walking route).
  • dmin - Drive Minutes - Sorts the results by shortest driving time (calculated as an actual driving route).
  • dm - Drive Miles - Sorts the results by shortest driving distance in miles (calculated as an actual driving route).
  • dk - Drive Kilometers - Sorts the results by shortest driving distance in kilometers (calculated as an actual driving route).
Default value is m
No
shapeFormat
String
These shapeFormats are also described in more detail on the Geometry page. Shape format options:
  • raw - shape is represented as float pairs
  • cmp - shape is represented as a compressed path string with 5 digits of precision
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
  • simple - WKT standard for Simple Features.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
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

Response Field Description
Corridor Search Response Fields
sessionId The session to pull the route ribbon from (This is only returned if a sessionId was given).
line
LineString
The LineString to generate the corridor from (This is only returned if a line was given).
Search Response Fields
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 - Miles
  • k - Kilometers
  • wmin - Walking Minutes
  • dmin - Drive Minutes
  • dm - Drive Miles
  • dk - Drive Drive Minutes
Default value is "m"
maxMatches
Integer
Maximum amount of results to return.
shapeFormat
String
Shape format of all shapePoints returned
  • raw - shape is represented as float pairs
  • cmp - shape is represented as a compressed path string with 5 digits of precision
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
  • simple - WKT standard for Simple Features.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
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

POST

https://www.mapquestapi.com/search/v2/corridor?key=KEY

Example Request Body

{
    "line": [
        40.078811,
        -76.730422,
        41.078811,
        -74.730422,
        40.078811,
        -74.730422,
        39.961879,
        -76.730422,
        39.961879,
        -76.730422
    ],
    "options": {
        "maxMatches": 4
    }
}
<search>
    <line>
        <latLng>
            <lat>40.078811</lat>
            <lng>-76.730422</lng>
        </latLng>
        <latLng>
            <lat>41.078811</lat>
            <lng>-74.730422</lng>
        </latLng>
        <latLng>
            <lat>40.078811</lat>
            <lng>-74.730422</lng>
        </latLng>
        <latLng>
            <lat>39.961879</lat>
            <lng>-76.730422</lng>
        </latLng>
        <latLng>
            <lat>39.961879</lat>
            <lng>-76.730422</lng>
        </latLng>
    </line>
    <options>
        <maxMatches>4</maxMatches>
    </options>
</search>

Example Response

{
  "searchResults": [
    {
      "resultNumber": 1,
      "distance": 0,
      "sourceName": "mqap.ntpois",
      "name": "Wayne C Parsil Atty",
      "shapePoints": [
        39.962044,
        -76.727974
      ],
      "distanceUnit": "m",
      "key": "4769550f-5359-48d7-b774-643060037e55",
      "fields": {
        "phone": "7178460606",
        "side_of_street": "R",
        "group_sic_code": "811103",
        "state": "PA",
        "lng": -76.727974,
        "group_sic_code_name": "(all) Lawyers",
        "city": "York",
        "country": "US",
        "group_sic_code_name_ext": "(all) Lawyers",
        "id": "275098197",
        "mqap_geography": {
          "latLng": {
            "lng": -76.727974,
            "lat": 39.962044
          }
        },
        "address": "2 W Market St",
        "postal_code": "17401",
        "name": "Wayne C Parsil Atty",
        "mqap_id": "4769550f-5359-48d7-b774-643060037e55",
        "group_sic_code_ext": "811103",
        "disp_lat": 39.962044,
        "lat": 39.962044,
        "disp_lng": -76.727974
      }
    },
    {
      "resultNumber": 2,
      "distance": 0,
      "sourceName": "mqap.ntpois",
      "name": "Gregory Martin Attorney",
      "shapePoints": [
        39.962044,
        -76.727974
      ],
      "distanceUnit": "m",
      "key": "7e9b8f0e-1594-43b4-a073-52d48b41d2f6",
      "fields": {
        "phone": "7178460606",
        "side_of_street": "R",
        "group_sic_code": "811103",
        "state": "PA",
        "lng": -76.727974,
        "group_sic_code_name": "(all) Lawyers",
        "city": "York",
        "country": "US",
        "group_sic_code_name_ext": "(all) Lawyers",
        "id": "277321182",
        "mqap_geography": {
          "latLng": {
            "lng": -76.727974,
            "lat": 39.962044
          }
        },
        "address": "2 W Market St",
        "postal_code": "17401",
        "name": "Gregory Martin Attorney",
        "mqap_id": "7e9b8f0e-1594-43b4-a073-52d48b41d2f6",
        "group_sic_code_ext": "811103",
        "disp_lat": 39.962044,
        "lat": 39.962044,
        "disp_lng": -76.727974
      }
    },
    {
      "resultNumber": 3,
      "distance": 0,
      "sourceName": "mqap.ntpois",
      "name": "John M Sofilka Atty",
      "shapePoints": [
        39.962044,
        -76.727974
      ],
      "distanceUnit": "m",
      "key": "bed85c8d-cb31-483f-988b-c3fd3a3c1013",
      "fields": {
        "phone": "7178460606",
        "side_of_street": "R",
        "group_sic_code": "811103",
        "state": "PA",
        "lng": -76.727974,
        "group_sic_code_name": "(all) Lawyers",
        "city": "York",
        "country": "US",
        "group_sic_code_name_ext": "(all) Lawyers",
        "id": "273305376",
        "mqap_geography": {
          "latLng": {
            "lng": -76.727974,
            "lat": 39.962044
          }
        },
        "address": "2 W Market St",
        "postal_code": "17401",
        "name": "John M Sofilka Atty",
        "mqap_id": "bed85c8d-cb31-483f-988b-c3fd3a3c1013",
        "group_sic_code_ext": "811103",
        "disp_lat": 39.962044,
        "lat": 39.962044,
        "disp_lng": -76.727974
      }
    },
    {
      "resultNumber": 4,
      "distance": 0,
      "sourceName": "mqap.ntpois",
      "name": "Dale E Anstine Atty",
      "shapePoints": [
        39.962044,
        -76.727974
      ],
      "distanceUnit": "m",
      "key": "22e488f4-a05b-4b68-bc65-72b51a024738",
      "fields": {
        "phone": "7178460606",
        "side_of_street": "R",
        "group_sic_code": "811103",
        "state": "PA",
        "lng": -76.727974,
        "group_sic_code_name": "(all) Lawyers",
        "city": "York",
        "country": "US",
        "group_sic_code_name_ext": "(all) Lawyers",
        "id": "277230502",
        "mqap_geography": {
          "latLng": {
            "lng": -76.727974,
            "lat": 39.962044
          }
        },
        "address": "2 W Market St",
        "postal_code": "17401",
        "name": "Dale E Anstine Atty",
        "mqap_id": "22e488f4-a05b-4b68-bc65-72b51a024738",
        "group_sic_code_ext": "811103",
        "disp_lat": 39.962044,
        "lat": 39.962044,
        "disp_lng": -76.727974
      }
    }
  ],
  "line": [
    40.078811,
    -76.730422,
    41.078811,
    -74.730422,
    40.078811,
    -74.730422,
    39.961879,
    -76.730422,
    39.961879,
    -76.730422
  ],
  "resultsCount": 4,
  "hostedData": [
    {
      "tableName": "mqap.ntpois",
      "extraCriteria": "",
      "columnNames": []
    }
  ],
  "totalPages": 1,
  "info": {
    "statusCode": 0,
    "copyright": {
      "text": "© 2024 MapQuest, Inc.",
      "imageUrl": "https://api.mqcdn.com/res/mqlogo.gif",
      "imageAltText": "© 2024 MapQuest, Inc."
    },
    "messages": []
  },
  "options": {
    "kmlStyleUrl": "http://www.search.mapquestapi.com/kml-default.kml",
    "shapeFormat": "raw",
    "exactLinks": false,
    "width": 0.5,
    "pageSize": 4,
    "currentPage": 1,
    "units": "m",
    "maxMatches": 4,
    "bufferedWidth": 0.25
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <info>
        <statusCode>0</statusCode>
        <messages/>
        <copyright>
            <imageUrl>https://api.mqcdn.com/res/mqlogo.gif</imageUrl>
            <imageAltText>© 2024 MapQuest, Inc.</imageAltText>
            <text>© 2024 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>
            <width>0.5</width>
            <exactLinks>false</exactLinks>
            <bufferedWidth>0.25</bufferedWidth>
        </options>
        <resultsCount>4</resultsCount>
        <totalPages>1</totalPages>
        <hostedDataList>
            <hostedData>
                <tableName>mqap.ntpois</tableName>
                <columnNames/>
            </hostedData>
        </hostedDataList>
        <searchResults>
            <searchResult>
                <key>4769550f-5359-48d7-b774-643060037e55</key>
                <name>Wayne C Parsil Atty</name>
                <resultNumber>1</resultNumber>
                <distance>4.0648644276084666E-5</distance>
                <distanceUnit>m</distanceUnit>
                <sourceName>mqap.ntpois</sourceName>
                <shapePoints type="point">
                    <latLng>
                        <lat>39.962044</lat>
                        <lng>-76.727974</lng>
                    </latLng>
                </shapePoints>
                <fields>
                    <phone>7178460606</phone>
                    <side_of_street>R</side_of_street>
                    <group_sic_code>811103</group_sic_code>
                    <state>PA</state>
                    <lng>-76.727974</lng>
                    <group_sic_code_name>(all) Lawyers</group_sic_code_name>
                    <city>York</city>
                    <country>US</country>
                    <group_sic_code_name_ext>(all) Lawyers</group_sic_code_name_ext>
                    <id>275098197</id>
                    <mqap_geography>POINT (-76.727974 39.962044)</mqap_geography>
                    <address>2 W Market St</address>
                    <group_sic_code_ext>811103</group_sic_code_ext>
                    <mqap_id>4769550f-5359-48d7-b774-643060037e55</mqap_id>
                    <name>Wayne C Parsil Atty</name>
                    <postal_code>17401</postal_code>
                    <disp_lat>39.962044</disp_lat>
                    <lat>39.962044</lat>
                    <disp_lng>-76.727974</disp_lng>
                </fields>
            </searchResult>
            <searchResult>
                <key>7e9b8f0e-1594-43b4-a073-52d48b41d2f6</key>
                <name>Gregory Martin Attorney</name>
                <resultNumber>2</resultNumber>
                <distance>4.0648644276084666E-5</distance>
                <distanceUnit>m</distanceUnit>
                <sourceName>mqap.ntpois</sourceName>
                <shapePoints type="point">
                    <latLng>
                        <lat>39.962044</lat>
                        <lng>-76.727974</lng>
                    </latLng>
                </shapePoints>
                <fields>
                    <phone>7178460606</phone>
                    <side_of_street>R</side_of_street>
                    <group_sic_code>811103</group_sic_code>
                    <state>PA</state>
                    <lng>-76.727974</lng>
                    <group_sic_code_name>(all) Lawyers</group_sic_code_name>
                    <city>York</city>
                    <country>US</country>
                    <group_sic_code_name_ext>(all) Lawyers</group_sic_code_name_ext>
                    <id>277321182</id>
                    <mqap_geography>POINT (-76.727974 39.962044)</mqap_geography>
                    <address>2 W Market St</address>
                    <group_sic_code_ext>811103</group_sic_code_ext>
                    <mqap_id>7e9b8f0e-1594-43b4-a073-52d48b41d2f6</mqap_id>
                    <name>Gregory Martin Attorney</name>
                    <postal_code>17401</postal_code>
                    <disp_lat>39.962044</disp_lat>
                    <lat>39.962044</lat>
                    <disp_lng>-76.727974</disp_lng>
                </fields>
            </searchResult>
            <searchResult>
                <key>bed85c8d-cb31-483f-988b-c3fd3a3c1013</key>
                <name>John M Sofilka Atty</name>
                <resultNumber>3</resultNumber>
                <distance>4.0648644276084666E-5</distance>
                <distanceUnit>m</distanceUnit>
                <sourceName>mqap.ntpois</sourceName>
                <shapePoints type="point">
                    <latLng>
                        <lat>39.962044</lat>
                        <lng>-76.727974</lng>
                    </latLng>
                </shapePoints>
                <fields>
                    <phone>7178460606</phone>
                    <side_of_street>R</side_of_street>
                    <group_sic_code>811103</group_sic_code>
                    <state>PA</state>
                    <lng>-76.727974</lng>
                    <group_sic_code_name>(all) Lawyers</group_sic_code_name>
                    <city>York</city>
                    <country>US</country>
                    <group_sic_code_name_ext>(all) Lawyers</group_sic_code_name_ext>
                    <id>273305376</id>
                    <mqap_geography>POINT (-76.727974 39.962044)</mqap_geography>
                    <address>2 W Market St</address>
                    <group_sic_code_ext>811103</group_sic_code_ext>
                    <mqap_id>bed85c8d-cb31-483f-988b-c3fd3a3c1013</mqap_id>
                    <name>John M Sofilka Atty</name>
                    <postal_code>17401</postal_code>
                    <disp_lat>39.962044</disp_lat>
                    <lat>39.962044</lat>
                    <disp_lng>-76.727974</disp_lng>
                </fields>
            </searchResult>
            <searchResult>
                <key>22e488f4-a05b-4b68-bc65-72b51a024738</key>
                <name>Dale E Anstine Atty</name>
                <resultNumber>4</resultNumber>
                <distance>4.0648644276084666E-5</distance>
                <distanceUnit>m</distanceUnit>
                <sourceName>mqap.ntpois</sourceName>
                <shapePoints type="point">
                    <latLng>
                        <lat>39.962044</lat>
                        <lng>-76.727974</lng>
                    </latLng>
                </shapePoints>
                <fields>
                    <phone>7178460606</phone>
                    <side_of_street>R</side_of_street>
                    <group_sic_code>811103</group_sic_code>
                    <state>PA</state>
                    <lng>-76.727974</lng>
                    <group_sic_code_name>(all) Lawyers</group_sic_code_name>
                    <city>York</city>
                    <country>US</country>
                    <group_sic_code_name_ext>(all) Lawyers</group_sic_code_name_ext>
                    <id>277230502</id>
                    <mqap_geography>POINT (-76.727974 39.962044)</mqap_geography>
                    <address>2 W Market St</address>
                    <group_sic_code_ext>811103</group_sic_code_ext>
                    <mqap_id>22e488f4-a05b-4b68-bc65-72b51a024738</mqap_id>
                    <name>Dale E Anstine Atty</name>
                    <postal_code>17401</postal_code>
                    <disp_lat>39.962044</disp_lat>
                    <lat>39.962044</lat>
                    <disp_lng>-76.727974</disp_lng>
                </fields>
            </searchResult>
        </searchResults>
        <line type="linestring">
            <latLng>
                <lat>40.078811</lat>
                <lng>-76.730422</lng>
            </latLng>
            <latLng>
                <lat>41.078811</lat>
                <lng>-74.730422</lng>
            </latLng>
            <latLng>
                <lat>40.078811</lat>
                <lng>-74.730422</lng>
            </latLng>
            <latLng>
                <lat>39.961879</lat>
                <lng>-76.730422</lng>
            </latLng>
            <latLng>
                <lat>39.961879</lat>
                <lng>-76.730422</lng>
            </latLng>
        </line>
    </search>
</response>