US States & Cities documentation

US States is your ticket to quickly getting an US based directory up and running in ExpressionEngine. It comes bundled with all US States, the biggest cities in each state and information about them (population, zip codes, latitude, maps, etc.) - and of course the tags needed to retrieve all of this information and implement a states/cities directory based website. US States & Cities consists of a module with tags, an extension and a fieldtype. The add-on can be used for any country/region, but it does comes bundled with US states and cities so those would have to be deleted and new states/regions/cities would have to be added manually. To have a look at a demo demo click here. Please note; the dataset is not 100% complete and does not include all minor cities in the United States (and all zip codes). We're working on getting a demo up and running of this addon so you can browse the dataset for yourself.


  • Download and unzip
  • Copy the contents of system/expressionengine/third_party/ from the zip to system/expressionengine/third_party/ on your EE install
  • In the backend, navigate to Addons -> Modules and then install the "US States & Cities" module.
  • Voilá! You can now use the tags in this documentation to implement your US directory website!

Control Panel / Settings

The addon comes with an administration panel which initially will display the list of states:

Clicking a state will take you to a list of cities in that state, where you can delete or add cities.

Clicking on a city will bring you to a page where you can edit city information (name, slug, population) - in addition to adding/removing zip codes from the city (with latitude and longitude information). Note that you can add a zip code, leaving longitude/latitude empty - in which case the Google Maps API will be contacted to retrieve the correct latitude/longitude information.

The settings panel is pretty basic for now:

Field Type

US States & Cities comes with a field type which can be used either to select a state or a city. The city selection is a basic dropdown of cities:

The city selection custom field saves the city_id - in addition to this you can specify a field to save the city slug to and a field to save the state slug to. This is recommended if the URL structure of your website require you to fetch channel entries by state / city slug (which would normally be the case).

These fields need to be created beforehand, and need to be of type text. You can hide these fields from the publish form using EE's publish layout functionality if you do not want to display them to the end user.

Also notice that "Is list of cities?" checkbox there. If this is left unticked the fieldtype will display a list of states instead of cities. This can be used for state selection - state_slug is what is saved for this fieldtype, as this is what most often will be used. The dropdown will look like this:



This tag is used to list all the states in the database, and it has these variables:

  • {state_slug} - the string used as url slug for this state (url_title) - ie "alabama")
  • {state_name} - the state name, ie. "Alabama"
  • {state_short_name} - the state short name, ie. "AL"

Example template code:

<h1>List of states</h1>

<li><a href='{path=us_states/{state_slug}}'>{state_name}</a> ({state_short_name})</li>

{exp:states:cities state_slug=''}

Retrieve a list of cities in a specific state. Remember to give it the state_slug parameter, which you can get from one of the segment variables for instance.

Available variables:

  • {city_slug} - the city url slug (url_title)
  • {city_name} - the name of the city

Example template code:

<h1>List of cities in {exp:states:state_name slug='{segment_2}'}</h1>
{exp:states:cities state_slug='{segment_2}'}
<li><a href='{path=us_states/{segment_2}/{city_slug}}'>{city_name}</a></li>


This tag is used to retrieve information about a specific city.


  • slug - required if not city_id is used, the slug of the city to retrieve information about
  • strong>state_slug - required if not city_id is used, the slug of the state of the city to retrieve information about (req. because the cities may have the same city slug).
  • city_id - retrieve a city by its id.
  • zip - retrieve a city by its zip code
  • map_zoom - optional, defaults to 12
  • map_width - optional, defaults to 400
  • map_height - optional, defaults to 400
  • map_add_city_marker - y/n - optional, defaults to y
  • map_marker_color - optional, defaults to 'blue'
  • strong>map_marker_label - optional, defaults to first letter in city name. NB! can only be 1 character
  • tag_prefix - optional, defaults to empty (no prefix) - use this to prefix all variables (in case of tag naming conflicts)

Available variables:

  • city_id - the database id of the city
  • city_slug - the url slug of the city
  • city_name - the name of the city
  • city_zip - the zip code of the city
  • state_name - the name of the state the city belongs to
  • state_short_name - the short name of the state the city belongs to (ie. AL)
  • state_slug - the url slug of the state the city belongs to
  • city_population - the population of the city
  • city_population_human - the population of the city, in a human readable format
  • city_longitude - the longitude of the city
  • city_latitude - the latitude of the city
  • city_map_image - an image link to a map (google static image)
  • city_map_width - the map image width
  • city_map_height - the map image height

Note the Google Maps Static Images have lots of configurable options, which you can append to {city_map_image} - read up on that here.

Example template:

{exp:states:city_info slug='{segment_3}' state_slug='{segment_2}' map_width="600" map_height="300"}

<h1>Welcome to {city_name}, <a href='{path=us_states/{state_slug}}'>{state_name}</a></h1>

<p>This city has a population of <strong>{city_population_human}</strong> people!</p>

<p>Default map:</p>
<img src='{city_map_image}' width="{city_map_width}" height="{city_map_height}"/>
<p>.. or we can add arguments to the image url like this (more info <a href="">here</a>):</p>
<img src='{city_map_image}&maptype=satellite' width="{city_map_width}" height="{city_map_height}"/>




<li>city_id: {city_id}</li>
<li>city_name: {city_name}</li>
<li>city_slug: {city_slug}</li>
<li>city_zip: {city_zip}</li>
<li>state_name: {state_name}</li>
<li>state_short_name: {state_short_name}</li>
<li>state_slug: {state_slug}</li>
<li>city_population: {city_population}</li>
<li>city_population_human: {city_population_human}</li>
<li>city_longitude: {city_longitude}</li>
<li>city_latitude: {city_latitude}</li>
<li>city_map_image: {city_map_image}</li>
<li>city_map_width: {city_map_width}</li>
<li>city_map_height: {city_map_height}</li>



{exp:states:redirect_by_zip zip='' redirect=''}

Use this to redirect to a specific state/city page based on a zip. This can for instance be useful in cases where you have a zip input field, or a dropdown and want to redirect users to a state/city listing based on the zip code they enter/select.

Parameters needed are zip (the zip code) and redirect which is the template group / url you want to redirect to. The redirect variable will basically be postfixed with /state_slug/city_slug/ and the user will be sent there.

Example template code:

{exp:states:redirect_by_zip zip="{segment_2}" redirect="available_houses"}

The code above will take the zip from the url segment, and redirect the users to a template group called "available_houses", so for instance would redirect to

{exp:states:city_name slug='' state_slug=''}

Use this to retrieve the city name by city/state slug.

For example: {exp:states:city_name slug='birmingham' state_slug='alabama'} will return "Birmingham".

{exp:states:city_id slug='' state_slug=''}

Use this to retrieve the city database id by city/state slug.

For example: {exp:states:city_id slug='birmingham' state_slug='alabama'} might return 42.

{exp:states:state_name slug=''}

Use this to retrieve the state name by its slug.