Add readme and license

1 files changed, 68 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e0c13bc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+Search postcodes for Norway
+===========================
+
+This gem is a simple interface to the Norwegian postcode database published by Bring. It allows you to search for and retreive entries in the postcode database.
+
+A rake task is included to fetch the actual postcode data as published by Bring.
+
+
+Installation
+------------
+
+In your Gemfile, add the following:
+
+    gem 'postcodes-norway'
+
+The run `bundle install` as usual.
+
+Fetch the data:
+
+    rake postcodes:fetch[output_dir]
+
+A file named "Postnummerregister_ansi.txt" will be placed in the specified `output_dir`.
+
+
+Usage
+-----
+
+Initialize the library:
+
+    require 'postcodes-norway'
+
+    PostCodes.load('output_dir/Postnummerregister_ansi.txt')
+
+Query for some postcodes:
+
+    p = PostCodes.search(1326)
+    puts p.city                 # => "LYSAKER"
+    puts p.municipality_name    # => "BÆRUM"
+    puts p.county               # => [2, "AKERSHUS"]
+
+    p1 = PostCodes.search('0666')
+    puts p1.city                # => "OSLO"
+    puts p1.municipality_name   # => "OSLO"
+    puts p1.county              # => [3, "OSLO"]
+
+
+Contributing
+------------
+
+Feel free to send suggestions or pull requests.
+
+License
+-------
+
+Copyright (C) 2015  Harald Eilertsen
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.