jgv / area Goto Github PK

View Code? Open in Web Editor NEW

176.0 5.0 58.0 3.73 MB

Perform a variety of conversions between places and area codes or zip codes.

Home Page: http://jonathanvingiano.com/area

License: MIT License

Ruby 100.00%

area's Introduction

Area

Hi. This gem allows you to perform the following conversions:

An area code to a region (state)
A state to an area code
A place to a zip code
A zip code to a place (control granularity with city and state options)
A zipcode to a lat/lon
A zipcode to just a lat
A zipcode to just a lon
A zipcode to its GMT offset
A state to its GMT offset
A lat/lon pair to a region
A lat/lon pair to its GMT offset
A lat/lon pair to its zip code

Area uses public domain data and does not rely on any external services (the internets). Usage is meant to be more lightweight than the Geocoder gem.

Installation

In your gemfile: gem 'area'

Usage

Convert an area code to a state/region

646.to_region #=> NY

Convert a state to an area code

"AK".to_area #=> ["907"]
"CT".to_area #=> ["203", "860"]
```

#### Convert a place to a zip code
```` ruby
"long island city, ny".to_zip #=> ["11101", "11109", "11120"]
"hastings on hudson".to_zip #=> ["10706"]
```

#### Convert a zip code to a place
```` ruby
"11211".to_region #=> "Brooklyn, NY"
"11211".to_region(:city => true) #=> "Brooklyn"
"11211".to_region(:state => true) #=> "NY"
```

#### Convert a zip code to a lat/lon
```` ruby
"11211".to_latlon #=> "40.71209, -73.95427"
```

#### Convert a zip code to a lat
```` ruby
"11211".to_lat #=> "40.71209"
```

#### Convert a zip code to a lon
```` ruby
"11211".to_lon #=> "-73.95427"
```

#### Get the GMT offset of a zipcode
```` ruby
"11211".to_gmt_offset #=> "-5"
```

#### Get the GMT offset of a state
```` ruby
"NY".to_gmt_offset #=> "-5" # by state
```

#### Determine daylight savings time observance of a zipcode
```` ruby
"11211".observes_dst? #=> true
```

#### Determine daylight savings time observance of a state
```` ruby
"NY".observes_dst? #=> true # by state
```

#### Convert a lat/lon pair to a zipcode
```` ruby
[40.71209, -73.95427].to_zip #=> "11211"
```

#### Convert a lat/lon pair to a region
```` ruby
[40.71209, -73.95427].to_region #=> "Brooklyn, NY"
```

#### Get the GMT offset for a lat/lon pair
```` ruby
[40.71209, -73.95427].to_gmt_offset #=> "-5"
```

#### Determine daylight savings time observance for a lat/lon pair
```` ruby
[40.71209, -73.95427].observes_dst? #=> true
```

## Testing and Contributing and Stuff

Contributions are more than welcome. I'm [testing](http://travis-ci.org/jgv/area) with minitest. This gem supports:

* Ruby 1.8.7
* Ruby 1.9.2
* Ruby 1.9.3
* JRuby 1.8
* JRuby 1.9
* Rubinius 1.8
* Rubinius 1.9

## Copyright

Copyright (c) 2012 Jonathan Vingiano. See [LICENSE](https://github.com/jgv/area/blob/master/MIT-LICENSE) for details.

area's People

Contributors

Stargazers

Watchers

Forkers

blakewilliams rthbound aaronfeng jamonholmgren jgarber adamnbowen adnantheexcellent 12spokes thuynguyen spnkr cklatt jfranz dpdearing orbanbotond unkleara johnnymugs pinchme bluetwin munya kylesziv lendsquare openbay fourfour mikestone14 charliehan barbershoplabs namakukingkong ckorhonen billr578 trumaker instamotor-labs mscheibe dahal jasnow michaelwiss obi4589 prsanjay mclark4386 concept47 thesquarefoot bradpurchase mresnickmdlive jakubonty catimm tweag hinthealth beasta ghiculescu minibardelivery honeypc

area's Issues

Throws exception on nine-digit zip code

This is easy enough I figure I'll send you a pull request later today, but thought I'd write an issue anyway to start a discussion about this. When I send a ZIP code with a +4, e.g. "60622-1234", Area raises an ArgumentError: "You must provide a valid area or zip code". For my purposes I don't really care about the +4, so I could filter it out before asking Area, but Area really should handle these kinds of ZIP codes as they are considered to be well-formatted and are accepted by the US Postal Service as valid zip codes.

I think it would be unreasonable to ask it to know exactly where each +4 zip code is, geographically (like, lat/lng should come from the first five digits because seriously nobody should care about the last four), but including the +4 is definitely not good enough cause for throwing an exception.

Have valid? method to test for valid inputs rather than raising exceptions.

Hi Jonathan! What a terrific and useful gem you have here! Nice work.

May I suggest that you implement a way to handle invalid data aside from raising an exception? For use cases involving user-generated input, it may be necessary to have some sort of validation test. Creating a rescue block for every usage makes for some unsightly code. It would be nice to be able to do something like:

postal_code="SE151AA" # a UK postal code
if postal_code.valid_zip_code?

do one thing

else
#do invalid zip code handling
end

Another problem with the way errors are currently handled is that you can pass it an invalid code and in some circumstances it will return nil. This inconsistency makes error handling more difficult:

"ABCDE".to_region
=> nil

Incorrect Longitudes in Data Set

The longitudes for for SF zip codes 94135.. 94188 seem to be off

Updates to zipcode data

I'm considering using area for a project that does a fair amount of geocoding already. Having a local database for US data would be a nice improvement. While the data is mostly static it does change from time to time. How does the area gem handle updates to the zipcode database?

Create separate methods for processing area codes versus zip codes

This might be an edge case, but I am using this gem to validate zip codes entered into a search field. I need to be able to make sure that "012" throws an error. However, since your to_region method treats a string length of 3 as an area code, "012".to_region is returning nil when I'm expecting an error.

I would create separate methods for processing area codes versus zip codes. And when checking zip codes, I wouldn't just check if the length is 5, I would check that the string is in the right format using this regex: /^\d{5}(-\d{4})?$/

Thoughts?

When postal code is not found to_region method returns entire hash of postal codes and regions

If you use "9888" as the postal code, and do to_region on it, you get the entire hash of regions.

I don't think this is useful. It would make more sense to return [] so that we can check that the the postal code is invalid.

zip code 80023 not in database

Hello,

First of all, thanks for writing this gem. I launched this gem on my website last night and found an issue with the database. I have a customer who's zip code is 80023 and was getting errors on my site saying that her zip code didn't exist. I looked through the zipcode database in this gem and noticed that 80023 wasn't there. This is concerning because I don't know if this is a fluke or if there are a lot of valid zip codes that don't exist in the database csv.

Any chance you can update the list of known zip codes to a more recent one?

Adnan

How often is the zipcode data refreshed?

I was just curious how often the source data is refreshed. I've read that the USPS updates zipcode mappings on a monthly basis, but I'd be happy a refresh just 3-4 times a year.

Also, would the gem's version get bumped if there were no code changes but new data loaded? If so, I think I'd opt to not fixing this gem's version in my Gemfile. A tad more transparency on this issue in the docs would be great.

Overall, though, thank you very much for such an easy to use gem!

Is this project still maintained?

None of the pull requests on this project have been commented on or accepted and there haven't been any commits in 4 years.

There are also 50 forks of this project in varying states of update.

Return closest zip for lat/long coordinates

Currently Array#to_region code just checks for an exact match, which is pretty much guaranteed to fail in case of user supplied coordinates from, say, geolocation apis. Shouldn't we at least try to return the closest region based on distance?