Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Grails plugin to provide utilities to populate the City and State from a Zip code

branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Zip-City-State Plugin

Provides utilities to populate the City and State from a given 5 digit zip code. Due to licensing concerns no postal code date will be packaged with this plugin. The original intent of this plugin was to allow users to easily implement their own zip code database and lookup. The design is such that you can easily utilize an external service if you would prefer.


This plugin requires jQuery (no strict requirement on version)


Add the following to the BuildConfig.groovy file of your Grails project:

plugins {
        compile(":zip-city-state:1.0") {
            excludes 'jquery'

The above assumes that you installed jQuery already in your project. If you have not you can remove the excludes line.

Implementation Instructions

Maintain your own database

  1. Create a domain class with the zip code info (city,state,zip). A simple example can be found in the project source ZipCode.
  2. Provide a service which implements the CityStateLookup interface. An example using the above domain class is provided in the project source ZipCodeService and copied here:

    class ZipCodeService implements CityStateLookup {
        ZipCityState lookupByZip(String code) {
            def zipCode = ZipCode.findByCode(code)
            zipCode ? [code:zipCode.code,,state:zipCode.state] as ZipCityState : null
  3. Tell the plugin the name of the service bean you created in step 2

    zipcitystate.cityStateLookupService.beanName = 'zipCodeService'
  4. Create your gsp a. Place the tag to include the necessary js on your page (will use the resources plugin if installed in your application)


    b. Bind the javascript function and event to your zip code field. An example usage is provided below:

    .on('zipChange',function(event, state, city, zip) {
       //populate the city and state
       //automatically move the cursor to the field that comes next
    .on('zipNotFound',function(event,zip) {
        //maybe display something or just do nothing
        $("zipError").html('Zip not found!');
  5. Test it out!

Use an external service

Start at step 2 above

Sample Application

Good news! This plugin is also a fully functional sample application. Simply download the source and fire it up.

Something went wrong with that request. Please try again.