Open Geocoding API

POST

Geocode Address

The geocoding service enables you to take an address and get the associated latitude and longitude.

Resource URL

http://open.mapquestapi.com/geocoding/v1/address

Resource Information

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

Parameters

Request Parameter	Description	Required?
key	The API Key, which is needed to make requests to MapQuest services.	Yes
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
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

Request Body

Body	Description	Required?
location	The location to geocode	Yes

Request Body Options

Body Option	Description	Required?
boundingBox	When using batch geocoding or when ambiguous results are returned, any results within the provided bounding box will be moved to the top of the results list. Bounding box format is: upper left latitude, upper left longitude, lower right latitude, lower right longitude.	No
ignoreLatLngInput	This option tells the service whether it should fail when given a latitude/longitude pair in an address or batch geocode call, or if it should ignore that and try and geocode what it can. true - The geocoder will ignore the LatLng specified in the location, and use the address info to perform geocode false - The geocoder will return a geoaddress object containing the LatLng passed in and write a warning message to Info block Default = false	No
thumbMaps	This 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. Default = true	No
maxResults	The number of results to limit the response to in the case of an ambiguous address. (-1 indicates no limit)	No
delimiter	Specifies the delimiter used in the csv response Comma Pipe Colon Semicolon Default is none. This option will only have an effect if outFormat=csv.	No
intlMode	Allows users of the International Geocoder to tell MapQuest how to handle a 5-box geocode. 5BOX - keeps the query as a 5-box and sends it to the TomTom International Geocoder as a 5-box. 1BOX - converts the 5-box query into a 1-box query and sends it to the TomTom International Geocoder. AUTO - handles the query in a way deemed most optimal by MapQuest. Currently this converts a 5-box query to a 1-box query across the board. Default = AUTO	No

Response

Response Field	Description
providedLocation	The provided location properties passed in the geocode request.
latLng	Returns the latitude/longitude for routing and is the nearest point on a road for the entrance.
street	Street address
adminArea6	Neighborhood name
adminArea5	City name
adminArea4	County name
adminArea3	State name
adminArea1	Country name
postalCode	Postal code
type	Type of location. 's' = stop (default) 'v' = via
dragPoint	Is 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)
displayLatLng	A lat/lng pair that can be helpful when showing this address as a Point of Interest.
geocodeQuality	The precision of the geocoded location. Refer to the Geocode Quality reference page for more information.
geocodeQualityCode	The five character quality code for the precision of the geocoded location. Refer to the Geocode Quality reference page for more information.
linkId	String that identifies the closest road to the address for routing purposes.
sideOfStreet	Specifies the side of street. 'L' = left 'R' = right 'M' = mixed 'N' = none (default)
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 about our status codes and error messages. The messages subfield is an array of error messages that describe the status

Example Request

POST

http://open.mapquestapi.com/geocoding/v1/address?key=KEY

{
  "location": "Washington,DC",
  "options": {
    "thumbMaps": false
  }
}

Example Response

{
  "info": {
    "statuscode": 0,
    "copyright": {
      "text": "© 2017 MapQuest, Inc.",
      "imageUrl": "http://api.mqcdn.com/res/mqlogo.gif",
      "imageAltText": "© 2017 MapQuest, Inc."
    },
    "messages": []
  },
  "options": {
    "maxResults": -1,
    "thumbMaps": false,
    "ignoreLatLngInput": false
  },
  "results": [
    {
      "providedLocation": {
        "street": "Washington,DC"
      },
      "locations": [
        {
          "street": "",
          "adminArea6": "",
          "adminArea6Type": "Neighborhood",
          "adminArea5": "Washington",
          "adminArea5Type": "City",
          "adminArea4": "District of Columbia",
          "adminArea4Type": "County",
          "adminArea3": "DC",
          "adminArea3Type": "State",
          "adminArea1": "US",
          "adminArea1Type": "Country",
          "postalCode": "",
          "geocodeQualityCode": "A5XAX",
          "geocodeQuality": "CITY",
          "dragPoint": false,
          "sideOfStreet": "N",
          "linkId": "282772166",
          "unknownInput": "",
          "type": "s",
          "latLng": {
            "lat": 38.892062,
            "lng": -77.019912
          },
          "displayLatLng": {
            "lat": 38.892062,
            "lng": -77.019912
          }
        }
      ]
    }
  ]
}

"Country","State","County","City","PostalCode","Street","Lat","Lng","DragPoint","LinkId","Type","GeocodeQualityCode","GeocodeQuality","SideOfStreet","DisplayLat","DisplayLng"
"US","DC","District of Columbia","Washington","","","38.892062","-77.019912","false","282772166","s","A5XAX","CITY","N","38.892062","-77.019912"