Skip to content

Geocoding API

POST Reverse Geocode

The reverse geocoding service allows a latitude and longitude to be converted to a location.

Note: For Reverse Geocode native language support to work, the client should pass a header parameter accept-language which takes ISO-2 country codes as its value with the request.

Resource URL

https://www.mapquestapi.com/geocoding/v1/reverse

Resource Information

Response FormatsJSON, XML, CSV
AuthenticationYes (Requires Key)
Rate LimitedYes

Request Parameters

Request ParameterDescriptionRequired
keyThe API Key, which is needed to make requests to MapQuest services.Yes
outFormatSpecifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
  • csv (character delimited)
Example: XML response
outFormat=xml
optional, defaults to json
callbackA 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.

Example: Callback
callback=reverseGeocodeResult
optional

Request Body

Request ParameterDescriptionRequired
locationThe latitude,longitude of the point to reverse geocode.

Example: latitude,longitude
"location": { "latLng": { "lat": 30.333472, "lng": -81.470448}}
Yes
includeNearestIntersectionReturns the nearest cross streets (intersection) to the given points.
  • true: nearest intersection is returned.
  • false: nearest intersection is not returned.
Example: Return Nearest Intersection
"includeNearestIntersection": true
optional, defaults to false
includeRoadMetadataReturns speed limit and toll road data, if available.
  • true: speed limit or toll road data is returned.
  • false: speed limit or toll road data is not returned.
Example: Road Metadata
"includeRoadMetadata": true
optional, defaults to false

Options Object

Request ParameterDescriptionRequired
thumbMapsThis parameter tells the service whether it should return a URL to a static map thumbnail image for a location being geocoded.
  • true: The response will include a URL to a static map image of the geocoded location.
  • false: The response will not include a static map image URL.
Example: Disable Static Map Response
"options": {"thumbMaps": false}
optional, defaults to true
delimiterSpecifies the delimiter used in the csv response
  • ,
  • |
  • :
  • ;
Example: Pipe Delimiter
"delimiter": "|"
optional, defaults to none, only in effect if outFormat=csv

Response Object

providedLocationThe provided location properties passed in the geocode request.
latLngReturns the latitude/longitude for routing and is the nearest point on a road for the entrance.
streetStreet address.
adminArea6Neighborhood name.
adminArea5City name.
adminArea4County name.
adminArea3State name.
adminArea1Country name.
postalCodePostal code.
typeType of location.
  • 's' = stop (default)
  • 'v' = via
roadMetadataReturns speed limit and toll road data, when available.
nearestIntersectionReturns nearest intersection (street pair) to a given point.
dragPointIs location a drag point? This option only applies when making a dragroute call.
  • true = location is a drag point
  • false = location is not a drag point (default)
displayLatLngA lat/lng pair that can be helpful when showing this address as a Point of Interest.
geocodeQualityThe precision of the geocoded location.

Refer to the Geocode Quality reference page for more information.
geocodeQualityCodeThe five character quality code for the precision of the geocoded location.

Refer to the Geocode Quality reference page for more information.
linkIdString that identifies the closest road to the address for routing purposes.
sideOfStreetSpecifies the side of street.
  • 'L' = left
  • 'R' = right
  • 'M' = mixed
  • 'N' = none (default)
infoThis field contains information about the response.

The statuscode subfield is an integer return value. Refer to the status codes page for more details about our status codes and error messages.

The messages subfield is an array of error messages that describe the status

Example Request

POST https://www.mapquestapi.com/geocoding/v1/reverse?key=KEY

Example Request Body

JSON
{
  "location": {
    "latLng": {
      "lat": 30.333472,
      "lng": -81.470448
    }
  },
  "options": {
    "thumbMaps": false
  },
  "includeNearestIntersection": true,
  "includeRoadMetadata": true
}
XML
<?xml version='1.0' encoding='utf-8'?>
<reverse>
  <location>
    <latLng>
      <lat>30.333472</lat>
      <lng>-81.470448</lng>
    </latLng>
  </location>
  <options>
    <thumbMaps>false</thumbMaps>
  </options>
  <includeNearestIntersection>true</includeNearestIntersection>
  <includeRoadMetadata>true</includeRoadMetadata>
</reverse>

Example Response

JSON
{
  "info": {
    "statuscode": 0,
    "copyright": {
      "text": "© 2023 MapQuest, Inc.",
      "imageUrl": "https://api.mqcdn.com/res/mqlogo.gif",
      "imageAltText": "© 2023 MapQuest, Inc."
    },
    "messages": []
  },
  "options": {
    "maxResults": 1,
    "thumbMaps": false,
    "ignoreLatLngInput": false
  },
  "results": [
    {
      "providedLocation": {
        "latLng": {
          "lat": 30.333472,
          "lng": -81.470448
        }
      },
      "locations": [
        {
          "street": "63 City Hall Sq",
          "adminArea6": "",
          "adminArea6Type": "Neighborhood",
          "adminArea5": "Boston",
          "adminArea5Type": "City",
          "adminArea4": "Suffolk",
          "adminArea4Type": "County",
          "adminArea3": "MA",
          "adminArea3Type": "State",
          "adminArea1": "US",
          "adminArea1Type": "Country",
          "postalCode": "02201-1001",
          "geocodeQualityCode": "L1AAA",
          "geocodeQuality": "ADDRESS",
          "dragPoint": false,
          "sideOfStreet": "L",
          "linkId": "0",
          "unknownInput": "",
          "type": "s",
          "latLng": {
            "lat": 30.333472,
            "lng": -81.470448
          },
          "displayLatLng": {
            "lat": 30.333472,
            "lng": -81.470448
          },
         "nearestIntersection": {
            "streetDisplayName": "Posey Cir",
            "distanceMeters": "851755.1608527573",
            "latLng": {
              "longitude": -87.523761,
              "latitude": 35.013434
            },
            "label": "Danley Rd & Posey Cir"
          },
          "roadMetadata": {
            "speedLimitUnits": "mph",
            "tollRoad": null,
            "speedLimit": 40
          }
        }
      ]
    }
  ]
}
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>&#169; 2023 MapQuest, Inc.</imageAltText>
      <text>&#169; 2023 MapQuest, Inc.</text>
    </copyright>
  </info>
  <results>
    <result>
      <providedLocation>
        <latLng>
          <lat>30.333472</lat>
          <lng>-81.470448</lng>
        </latLng>
      </providedLocation>
      <locations>
        <location>
          <street>12714 Ashley Melisse Blvd</street>
          <adminArea6 type='Neighborhood'></adminArea6>
          <adminArea5 type='City'>Jacksonville</adminArea5>
          <adminArea3 type='State'>FL</adminArea3>
          <adminArea4 type='County'>Duval</adminArea4>
          <postalCode>32225</postalCode>
          <adminArea1 type='Country'>US</adminArea1>
          <geocodeQuality>ADDRESS</geocodeQuality>
          <geocodeQualityCode>L1AAA</geocodeQualityCode>
          <dragPoint>false</dragPoint>
          <sideOfStreet>R</sideOfStreet>
          <displayLatLng>
            <latLng>
              <lat>30.333472</lat>
              <lng>-81.470448</lng>
            </latLng>
          </displayLatLng>
          <linkId>0</linkId>
          <unknownInput/>
          <type>s</type>
          <latLng>
              <lat>30.333472</lat>
              <lng>-81.470448</lng>
          </latLng>
          <mapUrl>
            <![CDATA[https://www.mapquestapi.com/staticmap/v5/getmap?key=KEY&type=map&size=225,160&pois=purple-1,30.3334721,-81.4704483,0,0,|&amp;center=30.3334721,-81.4704483&zoom=15&rand=-553163060]]>
          </mapUrl>
          <nearestIntersection>
            <streetDisplayName>Posey Cir</streetDisplayName>
            <latLng>
              <latitude>35.013434</latitude>
              <longitude>-87.523761</longitude>
            </latLng>
            <distance>851755.1608527573</distance>
            <label>Danley Rd & Posey Cir</label>
          </nearestIntersection>
          <roadMetaData>
            <tollRoad/>
            <speedLimit>40</speedLimit>
            <speedLimitUnits>mph</speedLimitUnits>
          </roadMetaData>
        </location>
      </locations>
    </result>
  </results>
  <options>
    <maxResults>1</maxResults>
    <thumbMaps>true</thumbMaps>
    <ignoreLatLngInput>false</ignoreLatLngInput>
    <boundingBox/>
  </options>
</response>
CSV
"Country","State","County","City","PostalCode","Street","Lat","Lng","DragPoint","LinkId","Type","GeocodeQualityCode","GeocodeQuality","SideOfStreet","DisplayLat","DisplayLng"
"US","FL","Duval","Jacksonville","32225","12714 Ashley Melisse Blvd","30.333472","-81.470448","false","0","s","L1AAA","ADDRESS","R","30.333472","-81.470448"