Skip to content
UGRC API Documentation

Street and zone geocoding

Geocoding allows you to get the geographic location (i.e., the geographical coordinates) from text. This UGRC API endpoint allows you to get the coordinates of a street address and zone. You can learn so much from a house, business, or other type of address once it has been geocoded. When you geocode data, you unlock the ability to visualize the data in a different way. And you can use our search endpoint to answer endless questions about your addresses or location.

URI Format

Parameters

Required path parameters

street

A Utah street address. A valid mailing address or structure does not need to exist at the input street to find a match. If the house number exists in the range of the street, a coordinate will be extrapolated from the road centerlines.

  • Type: string
  • Example: 326 east south temple st

zone

A Utah place name or a 5 digit zip code. The word, “City”, is optional. For example, “Sandy” and “Sandy City” are equivalent. The spelling needs to match (case-insensitive) an entry in the “Zone” column of this spreadsheet to have a chance of matching.

If a common place name is not in our list, please suggest an addition through a GitHub issue.

  • Type: string or number
  • Example: slc, 84111

Optional query string parameters

acceptScore

Every street and zone geocode will return a score for the match on a scale from 0-100. The score is a rating of how confident the system is in the choice of coordinates based on the input. For example, misspellings in a street name, omitting a street type when multiple streets with the same name exist, or omitting a street direction when the street exists in multiple address system quadrants will cause the result to lose points. Depending on your needs, you may need to limit the score the system will return. The default value of 70 will give acceptable results. If you need extra control, use the suggest and scoreDifference options

  • Type: number
  • Default: 70
  • Can be one of: 0-100

pobox

This option determines if the system should find a location for P.O. Box addresses. The default value of true, will return a location for a P.O. Box only when the input zone is a 5 digit zip code. The result will be where the mail is delivered. This could be a traditional post office, community post office, university, etc. When analyzing where people live, P.O. Box information will skew results since there is no correlation between where mail is delivered and where the owner of the mail resides.

  • Type: boolean
  • Default: true
  • Can be one of: true, false

locators

The locators are the search engine for address data. There are three options. The default value of all will use the highest score from the address point and road centerline data and provide the best match rate. Address point locations are used in the event of a tie. Address points are a collaboration with the counties to map structures or places where mail is delivered. Road centerlines are a dataset with every road the counties have shared with us and the range of numbers that road segment contains.

  • Type: string
  • Default: all
  • Can be one of: all, addressPoints, roadCenterlines

suggest

The default value of 0 will only return the highest match. To include more address candidates, set this value between 1-5. The candidates respect the acceptScore option.

  • Type: number
  • Default: 0
  • Can be one of: 0-5

scoreDifference

When suggest is set to the default value of 0, the difference in score between the top match and the next highest match is calculated and returned on the result object. This can help determine if there was a tie. The system will arbitrarily choose one result since they will have the same score. If the scoreDifference response value is 0, you can repeat the geocode with suggest > 0 and investigate the results.

  • Type: string
  • Default: all
  • Can be one of: all, addressPoints, roadCenterlines

spatialReference

The spatial reference defines how the coordinates will represent a location on the earth defined by how the round earth was made flat. The well known id’s (WKID) of different coordinate systems define if the coordinates will be stored as degrees of longitude and latitude, meters, feet, etc. This endpoint supports the WKIDs from the Geographic Coordinate System reference and the Projected Coordinate System reference. UTM Zone 12 N, with the WKID of 26912, is the default. This coordinate system is the most accurate reflection of Utah. It is recommended to use this coordinate system if length and area calculations are important as other coordinate systems will skew the truth.

  • Type: number
  • Default: 26912
Reference Information

format

There are three output formats for the result object. The default being empty. esrijson will parse into an esri.Graphic for mapping purposes and geojson will format as a Feature. If this value is omitted, the default json will be returned.

  • Type: string
  • Can be one of: esrijson, geojson

callback

The callback function to execute for cross domain javascript calls (jsonp). This API supports CORS and does not recommend the use of callback and jsonp.

  • Type: string

Response Shapes

{
  "result": {
    "location": {
      "x": 425608.67349758215,
      "y": 4513499.5088544935
    },
    "score": 100,
    "locator": "AddressPoints.AddressGrid",
    "matchAddress": "326 E SOUTH TEMPLE ST, SALT LAKE CITY",
    "inputAddress": "326 east south temple st, slc",
    "standardizedAddress": "326 east south temple street",
    "addressGrid": "SALT LAKE CITY"
  },
  "status": 200
}