QGIS Geocoding Plugin - US Address

Note: This plugin is not intended to be used with beta versions of QGIS. We suggest using it with the most recent stable version of QGIS for best performance.

Downloading the QGIS Geocoding Plugin

1. On your QGIS Desktop Application, navigate to the 'Plugins' option at the top of the toolbar and select 'Manage and Install Plugins...'

   

2. Navigate to the 'All' tab and search 'smarty'

   

3. Click 'Install Plugin'

4. And voila! You should see the Smarty plugin pop up next to the rest of your plugins in your QGIS toolbar!

   

     (Note: this is the icon for the Smarty Plugin)

Single Lookup

Makes use of US Street Address API and also US Autocomplete Pro API through the Smarty Python SDK.

Single Line Address Tab

Allows you to input, for geocoding, one address at a time.

The Single Line Address tool is free of charge and does not require a Smarty subscription.

Address Text Box: The complete address (address, city, state, zip).

• Freeform input can be up to 100 characters but only the first 50 will be considered for the street portion of the address. Freeform inputs should not include country information (like "USA")
• Users can geocode an address by adding it to the 'Address' text box. The Smarty US Autocomplete Pro API will provide suggestions as you type

• Addresses that contain secondary units will not return address information on entries associated with that address

  (NOTE: this is a limitation of the QGIS plugin)

• This is processed in what we call a "freeform" input (this is when the entire address is sent through the street field)

  (NOTE: The API is more rigid with freeform addresses (as it utilizes a strict match mode). Addresses that return an invalid match may have a higher success rate when entered in the 'Address Components' tab)

Address Components

Street: The street line of the address, or the entire address ("freeform" input).

City: The city name.

State: The state name or abbreviation.

ZIP Code: The ZIP Code.

(NOTE: When submitting addresses in this way, setting match to invalid will prevent the API from finding valid matches for ambiguous address input)

New Layer vs Existing Layer

Users must choose to either create a new layer or use an existing layer before they can geocode an address.

The following error message will be returned if a layer is not specified:

New Layer

If the user chooses to create a new layer a textbox will appear for the user to name the new layer. If the user does not put anything in this box, it will default name the new layer to 'Smarty.'

Existing Layer

The 'Existing Layer' option will be disabled unless there are layers in the current project that have been created by Smarty.

The 'Existing Layer' will only allow users to add addresses to layers and shapefiles that have been created by the Smarty plugin that are currently open in the open project.

If the user chooses to add the address to an existing layer, then a drop-down box will appear with the layers that have been previously created by the Smarty plugin; from which, they can select which existing layer they would like to add the address to.

Point ID

The user has the option to add an ID to the address they are adding to a new or existing layer.

If the user has chosen to use an existing layer which has an ID for every address then the user WILL be required to add an ID for that address. They will not be able to process their address if they have not added an ID. They will see an error message like this:

If the user wants to add an ID to a new layer (that doesn't NEED an ID, but they indicated a desire to add an ID by checking the 'Point ID' check box) and does not enter anything in the ID text box they will receive the following error:

If the user has chosen an existing layer that does not have an ID for every address then the 'Point ID' checkbox and the corresponding text box will remain disabled. The user will not be able to add an ID for the address for the existing layer.

Point Label

The user can add one label for the point:

• If the user does not add anything to the 'Point Label' textbox, no label will be set or shown on the output
• If the user does add text to the 'Point Label' textbox, it will display underneath the lat/long point

Output Symbol

The default symbol is 'star.'

The user can choose which output symbol they would like to see when the address has been processed. If our Smarty API finds a valid match then the plugin will output the geolocation of the address represented by the symbol at the Latitude and Longitude of the address.

The user can choose between this list of symbols from the plugin:

• 'star', 'regular_star', 'square', 'cross', 'rectangle', 'diamond', 'pentagon', 'triangle', 'equilateral_triangle', 'circle', 'arrow', 'filled_arrowhead', and 'x'

• The user can also change the symbology using QGIS after the address has been processed by:

  • Clicking on layer → Symbology → Simple Marker

Here is an example of the output of the geocode of an address using the symbol 'star':

Point Size

The user can change and set the size of the symbol (the number represents millimeters).

The default is set to 10 mm.

This can be changed using QGIS after the address has been processed by:

• Clicking on layer → Symbology → Size

Symbol Color

The user can choose the color of the symbol that is added to the layer.

The default color is:

• HEX: #ff0016
• RGB: 255, 0, 22

What is shown in the dialogue box is the default color.

The user can change the color of symbols after the address has been processed by:

• Clicking on the layer → Symbology → Color

Zoom In

The user has the option to zoom into the output point.

The checkbox is checked by default and QGIS will zoom in on the processed address.

Process Lookup

This button will send the address to the Smarty API, which will return the API results.

Visit Smarty

A link that will take users to the Smarty Rooftop Geocoding page, where they can:

• Find more information on our US Rooftop Geocoding product
• Browse US Rooftop Geocoding subscription prices
• Try a US Rooftop Geocoding demo

Results

Summary: Returns a summary of the results from the address sent to the API.

• If the API finds no match for the address the user will see:

  No Match - The address is invalid.

• If the API finds no match for the address, but a PO Box for the address the user will see:

  No Match - PO Box Only. The ZIP Code is PO Box delivery only.

• If the API finds a match for the address, but the address is vacant the user will see:

  Match-Vacant - The address is valid but vacant.

• If the API finds a match for the address, but the address is inactive the user will see:

  Match-Inactive - The address is valid but inactive.

• If the API finds a match for the address, but the address is not a postal match the user will see:

  Match-Non-Postal - A match was made to a valid non-postal address.

• If the API finds a match for the address, and the address is a postal address the user will see:

  Valid Match - A valid match was made to a postal address.

Address: Combination of the:

• Primary Number, Street Predirectional, Street Name, and Street Post Direction

City: The USPS-preferred city name for this particular address, or an acceptable alternate if provided by the user.

Zip: The 5-digit ZIP Code.

Zip+4: The 4-digit add-on code (more specific than 5-digit ZIP).

Latitude: The horizontal component used for geographic positioning. It is the angle between 0° (the equator) and ±90° (north or south) at the poles. It is the first value in an ordered pair of (latitude, longitude). A negative number denotes a location below the equator; a positive number is above the equator. Combining lat/long values enables you to pinpoint addresses on a map.

Longitude: The vertical component used for geographic positioning. It is the angle between 0° (the Prime Meridian) and ±180° (westward or eastward). It is the second number in an ordered pair of (latitude, longitude). A negative number indicates a location west of Greenwich, England; a positive number east. Combining lat/long values enables you to pinpoint addresses on a map.

Precision: Indicates the precision of the latitude and longitude values.

• Unknown — Coordinates not known. Reasons could include: address is invalid, military address (APO or FPO), lat/lon coordinates not available
• Zip5 — Accurate to a 5-digit ZIP Code level (least precise)
• Zip6 — Accurate to a 6-digit ZIP Code level
• Zip7 — Accurate to a 7-digit ZIP Code level
• Zip8 — Accurate to an 8-digit ZIP Code level
• Zip9 — Accurate to a 9-digit ZIP Code level (most precise with the basic subscription)
• Street — Accurate to a position along the street proportional to the house/building number.
• Parcel — Accurate to the centroid of a property parcel
• Rooftop — Accurate to the rooftop of a structure for this address

(NOTE: Concerning addresses for which the ZIP9 precision is not available, the ZIP# precision is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits)

Metadata

Extra information on the given address

County Name: The name of the county in which the address is located.

County FIPS: The 5-digit county FIPS (Federal Information Processing Standards) code. It is a combination of a 2-digit state FIPS Code and a 3-digit county code assigned by the NIST (National Institute of Standards and Technology).

Congressional District: The congressional district to which the address belongs. Output will be two digits from 01 - 53 or "AL." "AL" means that the entire state (or territory) is covered by a single congressional district. These include Alaska, Delaware, Montana, North Dakota, South Dakota, Vermont, Wyoming, Washington DC, Virgin Islands, and other territories.

Time Zone: Indicates the common name of the time zone associated with the address.

• Valid Responses:
• Alaska, Atlantic, Central, Eastern, Hawaii, Mountain, None, Pacific, Samoa, UTC+9, UTC+10, UTC+11, UTC+12

Residential/Commercial: Residential Delivery Indicator (residential or commercial)

• Residential — The address is a residential address
• Commercial — The address is a commercial address
• [blank] — This happens when the address is invalid, or we don't have enough information to ascertain RDI status. The Bulk Address Validation Tool translates a [blank] RDI value to "Unknown"

(NOTE: For some reason, known only to the US Postal Service, PO Boxes are always marked as "Residential")

Daylight Savings Time: Indicates if the time zone "obeys," or, in other words, adjusts their clocks forward and back with the seasons. This information is particularly useful to determine time in other time zones with areas that may or may not use daylight saving time - for example, Arizona, Hawaii, and, of all places, Indiana.

• True — Time zone observes daylight saving time
• If dst is absent from the response, then time zone does not observe daylight saving time

Batch Lookup

Smarty customers who have a subscription to US Rooftop Geocoding have the additional benefit of batch geocoding. This feature is useful when you need to visualize the relationship between several addresses all at once. Visit our US Rooftop Geocoding pricing page for more information regarding subscriptions.

Authentication

This is where users should provide their Smarty Auth ID and Auth Token.

If there have been no valid credentials added to the plugin the user will not be able to use this section of the dialogue box.

To Add Credentials:

• User enters their Auth ID and Auth Token
• When the user clicks on the 'Add Tokens' button the plugin will run a lookup on the following Chick-Fil-A valid address: '484 W Bulldog Blvd, Provo, UT 84604'

• If the user adds a valid Auth ID and Auth Token they will receive a message like this:

  

  (This portion of the dialogue box will be set to enabled so that they can perform batch lookups)

• If the user adds invalid credentials they will receive an error message like this:

  

• If the user forgets to add the Auth ID they will receive an error message like this:

  

• If the user forgets to add the Auth Token they will receive an error message like this:

  

• If the user forgets to add the Auth ID and the Auth Token they will receive an error message like this:

  

(NOTE: Users should add a Secret Key and NOT an Embedded Key. Through the use of our smartystreets_python_sdk we are building the credentials for the client using the StaticCredentials object)

CSV File

Tab where users can add information regarding their CSV that contains address information.

Select an Input CSV File: This is where the user can choose a CSV file located on their computer that contains address information that they would like to process.

Reset: If the user clicks the 'Reset' button the fields will be reset and the CSV file chosen will be rest to nothing.

Add CSV: If the user clicks the 'Add CSV' button the drop downs for 'Address', 'City', 'State', and 'ZIP Code' will be populated with all the column names in the provided CSV file.

The plugin will search for column names to autopopulate the desired fields:

• Address dropdown searches for column names:

  • 'address', 'street', and 'addr'

• City dropdown searches for column names:

  • 'city'

• State dropdown searches for column names:

  • 'state' and 'st'

• ZIP Code dropdown searches for column names:

  • 'Zip', 'zipcode', 'zip_code', and 'zip code'

(NOTE: These searches are case-insensitive)

If none of the dropdowns find relevant column names it will autopopulate with '----'.

The user can change which column they would like to use for each dropdown.

Component Addresses

If the user's CSV has the address components in different columns then they will want to use the component address feature by NOT checking the 'Single Line Address' box.

If the user's CSV has the address components in different columns they must provide which of their CSVs' columns correspond with the dropdowns named:

• Address
• City
• State
• ZIP Code

If the user has an ID for each of the addresses then the user needs to check the checkbox 'Primary Key' and indicate which of their CSV columns represents the ID for each address.

• If this information is given, the plugin will output the id with each of the processed addresses
• If the information is not given, the plugin will autogenerate an ID for every address processed starting from 1 and incrementing for every address. This information will be on the output of the batch

Single Line Addresses

If the user's CSV has the address components all in one column they should check the checkbox called 'Single Line Address'.

If the user's CSV has the address components all in one column they must provide that information for the 'Address' dropdown.

If the user has an ID for each of the addresses then the user needs to check the checkbox 'Primary Key' and indicate which of their CSV columns represents the ID for each address.

If this information is given, the plugin will output the id with each of the processed addresses.

If the information is not given, the plugin will autogenerate an ID for every address processed starting from 1 and incrementing for every address. This information will be on the output of the batch.

Primary Key: This is a way for the user to indicate if they already have an ID associated with every address.

If they provide a column that is associated with their ID then it will appear on the output with every address.

If they do not provide a column that is associated with their ID then we will generate an unique ID for every address starting with 1.

Address: The street line of the address, or the entire address ("freeform" input).

• Freeform input can be up to 100 characters but only the first 50 will be considered for the street portion of the address. Freeform inputs should omit any form of country information (like "USA")

City: The city name.

State: The state name or abbreviation.

ZIP Code: The ZIP Code.

Save Output - CSV Name: A place for the user to indicate where they would like the CSV that contains the processed and cleansed addresses on their computer.

• This CSV will be saved once the entire batch has been processed

Display Output: The user can decide whether they would like the processed addresses displayed on a newly created layer or not.

• This checkbox is checked by default, and the addresses will be displayed after all the addresses have been processed
• If the user does not want to create a new layer or have the addresses added to this layer then the user can uncheck this box

Process Batch: This is a button that will start the processing of the batch addresses.

• The button will show the user the % of completed addresses as the batch is running

Set Features

Tab where users can set the output appearance of addresses for the batch.

Output Symbol

The default symbol is 'star'.

The user can choose which output symbol they would like to see when the address has been processed. If Smarty's API finds a valid match then the plugin will output the geolocation of the address represented by the symbol at the Latitude and Longitude of the address.

Here is an example of the output of an address using the symbol 'star':

The user can choose between this list of symbols from the plugin:

• Star, regular_star, square, cross, rectangle, diamond, pentagon, triangle, equilateral_triangle, circle, arrow, filled_arrowhead, and x
• The user can also change the symbology using QGIS after the address has been processed

Symbol Color

The default color is:

• HEX: #ff0016
• RGB: 225, 0, 22

The user can choose the color of the symbol that is added to the layer. What is shown in the dialogue box is the default color.

Point Label

The default value is 'None.'

'None' → will not add a label to the output points or to the attributes associated with that layer.

This is a dropdown that gets populated with each of the provided CSVs' columns (plus 'None'). The user can choose one of these columns for the label. It will appear underneath the point for the address.

Point Size

The default is set to 10 mm.

The user can change and set the size of the symbol.

This can be changed using QGIS after the address has been processed.

Layer Name

The default value is 'Smarty.'

• If the user does not add anything to the 'Layer Name' textbox, it will be named 'Smarty'

This is where the user can specify the name of the newly created layer.