How to Geocode With the API

Step 4: Understanding the Geocoding Response

If you went through step 3 and geocoded the address of the White House, you would have received the following JSON response back:

 "lat": 38.8986709360362,
 "lon": -77.0351147858455,
 "address": {
   "address": "1600 Pennsylvania Ave NW, Washington, DC 20502",
   "prefix": null,
   "number": "1600",
   "street_name": "Pennsylvania",
   "street_type": "Ave",
   "suffix": "NW",
   "unit": null,
   "city": "Washington",
   "state": "DC",
   "zip": "20502"

Most of these fields are straightforward, but let’s walk through a few that are less obvious.

Prefix: This field may contain a direction like N, NW, S, W, etc. that comes before the street name in the address. For example, with an address like “1504 S Main Street…”, the prefix would be “S”.

Suffix: Similar to the prefix field above, but comes after the street name. For example, with an address like “1600 Pennsylvania Ave NW…”, the suffix would be “NW”.

Unit: This field may contain an internal unit number like “Apt 104” or “Suite 237”. For example, with an address like “500 Napa Valley Drive Apt 201…”, the unit would be “Apt 201”.

Appending Additional Data About Your Address

In addition to geocoding, gives you the option of appending data to your JSON response. For example, to get information about an address’s school district, you could add the “fields” parameter to our previous request like this:

Valid options for the “fields” parameter are as follows. You can request multiple data fields in a single request by separating them with commas (i.e. “...fields=geography,school_district”)

school_district: Returns the school district(s) for the address. This may include both the elementary and secondary school districts, or only the unified school district depending on the school district structure for the area in question.

geography: Returns information about the census geography delineations for the address, such as county, tract, block group, and block.

congressional_district: Returns the congressional district for the address.

state_legislative_district: Returns the state legislative districts (house and senate) for the address.

When and When Not to use

Consideration: Region of the world and address completeness can geocode any address in the United States, provided that it is fairly complete and free of mistakes. A good example of a well formed address is “6000 Universal Blvd, Orlando, FL 32819” (that’s The Wizarding World of Harry Potter for those keeping track!). Note that each part of the address is separated by a comma and that all parts of the address are present. It’s not required that the address be complete, and in many cases can fill in missing information, but completeness will help the accuracy of your results.

If you have a large number of addresses outside of the United States another solution like the OpenCage Geocoder may be a better fit. If you have very unpredictable or incomplete addresses, an address verification service like SmartyStreets may be a good fit.

Consideration: How will you use the resulting latitude/longitude coordinates?
If you will be displaying coordinates on a freely available map from services like Google Maps or MapQuest, you may want to consider using the corresponding Google or MapQuest geocoding API, however be sure to familiarize yourself with their terms of service as they restrict how you can use the geocoding results.

If you plan on storing the resulting coordinates or using them in a paid product, the free services from Google, MapQuest, etc. aren’t an option. has no restrictions on how you use or display the data you request.

Be sure to read the next Mapping article: How to Search Locations by Travel Time With the iGeolise TravelTime API


Comments (0)