Added Documentation

docs/features/Confidence Score.md

@@ -0,0 +1,30 @@
+# Confidence Score
+
+Based from OpenCage's API
+
+[OpenCage API](http://geocoder.opencagedata.com/api.html#quickstart)
+
+## Geocoding Confidence
+
+The OpenCage Geocoder will always attempt to find a match for as many parts of a query as it can, but this isn't always possible to do. Where a partial match is made, for example a street name can be matched but a specific house number on that street cannot be matched, the geocoder will still return a result but the granularity of the match will not be as high as if the house number was matched.
+
+The confidence that the geocoder has in a match returned in the confidence field. This contains a value between 0 and 10, where 0 reflects no confidence and 10 reflects high confidence.
+
+Confidence is calculated by measuring the distance in kilometres between the South West and North East corners of each results bounding box; a smaller distance represents a high confidence while a large distance represents a lower confidence.
+
+Please note, you can supply the optional min_confidence parameter (see below).
+
+
+|Score |       Description          |
+|:----:|:---------------------------|
+| 10   | less than 0.25 km distance |
+| 9    | less than 0.5 km distance  |
+| 8    | less than 1 km distance    |
+| 7    | less than 5 km distance    |
+| 6    | less than 7.5 km distance  |
+| 5    | less than 10 km distance   |
+| 4    | less than 15 km distance   |
+| 3    | less than 20 km distance   |
+| 2    | less than 25 km distance   |
+| 1    | 25 km or greater distance  |
+| 0    | unable to determine a bounding box|

docs/features/GeoJSON.md

@@ -0,0 +1,52 @@
+# GeoJSON Support
+
+GeoJSON is a format for encoding a variety of geographic data structures. A complete GeoJSON data structure is always an object (in JSON terms). In GeoJSON, an object consists of a collection of name/value pairs -- also called members. For each member, the name is always a string. Member values are either a string, number, object, array or one of the literals: true, false, and null.
+
+[GeoJSON Specification](http://geojson.org/geojson-spec.html)
+
+## Python Example
+
+```python
+>>> import geocoder
+>>> g = geocoder.google("New York City")
+>>> g.geojson
+...
+```
+
+## GeoJSON Output
+
+The difference between the GeoJSON and JSON response is the `geometry` attribute is in accordance with GeoJSON specification; All attributes are nested in the `properties` attribute and the `bbox` (bounding box) is formatted to the GeoJSON spec.
+
+```json
+{
+    "geometry": {
+        "type": "Point", 
+        "coordinates": [
+            -74.0059413, 
+            40.7127837
+        ]
+    }, 
+    "type": "Feature", 
+    "properties": {
+        "status": "OK", 
+        "city": "New York", 
+        "confidence": 1, 
+        "ok": true, 
+        "country": "United States", 
+        "provider": "google", 
+        "location": "New York City", 
+        "state": "New York", 
+        "address": "New York, NY, USA", 
+        "lat": 40.7127837, 
+        "lng": -74.0059413, 
+        "quality": "locality", 
+        "accuracy": "APPROXIMATE"
+    }, 
+    "bbox": [
+        -74.25908989999999, 
+        40.4913686, 
+        -73.70027209999999, 
+        40.91525559999999
+    ]
+}
+```

docs/features/OpenStreetMap.md

@@ -0,0 +1,29 @@
+# OpenStreetMap
+
+Address information can be added to OpenStreetMap using a variety of methods, such as adding a simple node containing an address, adding address information to a building or site outline, or alternatively to an entrance node for the building.
+
+[OpenStreetMap Addresses Specification](http://wiki.openstreetmap.org/wiki/Addresses)
+
+## Python Example
+
+```python
+>>> import geocoder
+>>> g = geocoder.google('11 Wall Street, New York')
+>>> g.osm
+...
+```
+
+## OSM Output
+
+```json
+{
+    "addr:housenumber": "11",
+    "addr:street": "Wall Street",
+    "addr:postal": "10005",
+    "addr:city": "New York",
+    "addr:state": "New York",
+    "addr:country": "United States",
+    "y": 40.7069226,
+    "x": -74.0111421
+}
+```

docs/features/Well-Known Text.md

@@ -0,0 +1,14 @@
+# Well Known Text
+
+Well-known text (WKT) is a text markup language for representing vector geometry objects on a map, spatial reference systems of spatial objects and transformations between spatial reference systems. A binary equivalent, known as well-known binary (WKB), is used to transfer and store the same information on databases, such as PostGIS, Microsoft SQL Server and DB2. The formats were originally defined by the Open Geospatial Consortium (OGC) and described in their Simple Feature Access and Coordinate Transformation Service specifications.
+
+[Wikipedia WKT](http://en.wikipedia.org/wiki/Well-known_text)
+
+# Python Example
+
+```python
+>>> import geocoder
+>>> g = geocoder.google('New York City')
+>>> g.wkt
+'POINT(-74.0111421 40.7069226)'
+```

docs/providers/ArcGIS.md

@@ -0,0 +1,50 @@
+# ArcGIS REST API
+
+The World Geocoding Service finds addresses and places in all supported countries
+from a single endpoint. The service can find point locations of addresses,
+business names, and so on.  The output points can be visualized on a map,
+inserted as stops for a route, or loaded as input for a spatial analysis.
+an address, retrieving imagery metadata, or creating a route.
+
+## Python Example
+
+```python
+>>> import geocoder
+>>> g = geocoder.arcgis('New York City')
+>>> g.json
+...
+```
+
+## API Reference
+
+https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find.htm
+
+## OSM Quality (1/6)
+
+- [ ] addr:housenumber
+- [ ] addr:street
+- [ ] addr:city
+- [ ] addr:state
+- [ ] addr:country
+- [x] **addr:postal**
+
+## Attributes (12/18)
+
+- [ ] accuracy
+- [x] **address**
+- [x] **bbox**
+- [ ] city
+- [x] **confidence**
+- [ ] country
+- [ ] housenumber
+- [x] **lat**
+- [x] **lng**
+- [x] **location**
+- [x] **ok**
+- [x] **postal**
+- [x] **provider**
+- [x] **quality**
+- [x] **score**
+- [ ] state
+- [x] **status**
+- [ ] street

docs/providers/Bing.md

@@ -0,0 +1,45 @@
+# Bing
+
+The Bing™ Maps REST Services Application Programming Interface (API)
+provides a Representational State Transfer (REST) interface to
+perform tasks such as creating a static map with pushpins, geocoding
+an address, retrieving imagery metadata, or creating a route.
+Using Geocoder you can retrieve Bing's geocoded data from Bing Maps REST Services.
+
+## Python Example
+
+```python
+>>> import geocoder # pip install geocoder
+>>> g = geocoder.bing('<address>')
+>>> g.lat, g.lng
+45.413140 -75.656703
+...
+```
+
+## Geocoder Attributes
+
+* accuracy
+* address
+* bbox
+* country
+* lat
+* lng
+* locality
+* location
+* postal
+* provider
+* quality
+* route
+* state
+* status
+
+## Parameters
+
+* :param location: Your search location you want geocoded.
+* :param key: (optional) use your own API Key from Bing.
+
+## References
+
+* [GitHub Repo](https://github.com/DenisCarriere/geocoder)
+* [GitHub Wiki](https://github.com/DenisCarriere/geocoder/wiki)
+* [Bing Maps REST Services](http://msdn.microsoft.com/en-us/library/ff701714.aspx)

docs/providers/CanadaPost.md

@@ -0,0 +1,43 @@
+# CanadaPost
+
+The next generation of address finders, AddressComplete uses intelligent, fast
+searching to improve data accuracy and relevancy. Simply start typing a business
+name, address or Postal Code and AddressComplete will suggest results as you go.
+Using Geocoder you can retrieve CanadaPost's geocoded data from Addres Complete API.
+
+## Python Example
+
+```python
+>>> import geocoder
+>>> g = geocoder.canadapost('<address>')
+>>> g.postal
+'K1R 7K9'
+...
+```
+
+## Geocoder Attributes
+
+* address
+* country
+* key
+* locality
+* location
+* ok
+* postal
+* provider
+* quality
+* route
+* state
+* status
+* street_number
+
+## Parameters
+
+* :param ``location``: Your search location you want geocoded.
+* :param ``key``: (optional) use your own API Key from CanadaPost Address Complete.
+
+## References
+
+* [GitHub Repo](https://github.com/DenisCarriere/geocoder)
+* [GitHub Wiki](https://github.com/DenisCarriere/geocoder/wiki)
+* [Addres Complete API](https://www.canadapost.ca/pca/)

docs/providers/FreeGeoIP.md

@@ -0,0 +1,100 @@
+FreeGeoIP.net
+=============
+freegeoip.net provides a public HTTP API for software developers to 
+search the geolocation of IP addresses. It uses a database of IP addresses 
+that are associated to cities along with other relevant information like 
+time zone, latitude and longitude.
+
+You're allowed up to 10,000 queries per hour by default. Once this 
+limit is reached, all of your requests will result in HTTP 403, 
+forbidden, until your quota is cleared. 
+
+API Reference
+-------------
+http://freegeoip.net/
+
+OSM Quality (4/6)
+-----------------
+- [ ] addr:housenumber
+- [ ] addr:street
+- [x] addr:city
+- [x] addr:state
+- [x] addr:country
+- [x] addr:postal
+
+Examples
+--------
+**CLI**
+
+```bash
+$ geocode '99.240.181.199' --provider freegeoip --pretty --geojson
+$ geocode '99.240.181.199' --provider freegeoip --pretty --json
+$ geocode '99.240.181.199' --provider freegeoip --pretty --osm
+```
+**iPython**
+
+```python
+$ ipython
+>>> import geocoder
+>>> g = geocoder.freegeoip('99.240.181.199')
+<[OK] Freegeoip - Geocode [Ottawa, Ontario Canada]>
+>>> g.geojson
+>>> g.json
+>>> g.osm
+```
+GeoJSON
+-------
+```json
+{
+    "geometry": {
+        "type": "Point", 
+        "coordinates": [
+            -75.691, 
+            45.413
+        ]
+    }, 
+    "type": "Feature", 
+    "properties": {
+        "status": "OK", 
+        "city": "Ottawa", 
+        "ip": "99.240.181.199", 
+        "address": "Ottawa, Ontario Canada", 
+        "provider": "freegeoip", 
+        "time_zone": "America/Toronto", 
+        "state": "Ontario", 
+        "location": "99.240.181.199", 
+        "country": "Canada", 
+        "postal": "K2P"
+    }
+}
+```
+JSON
+----
+```json
+{
+    "status": "OK", 
+    "city": "Ottawa", 
+    "ip": "99.240.181.199", 
+    "address": "Ottawa, Ontario Canada", 
+    "provider": "freegeoip", 
+    "time_zone": "America/Toronto", 
+    "state": "Ontario", 
+    "location": "99.240.181.199", 
+    "country": "Canada", 
+    "lat": 45.413, 
+    "lng": -75.691, 
+    "postal": "K2P"
+}
+```
+OSM
+---
+```json
+{
+    "addr:postal": "K2P", 
+    "addr:city": "Ottawa", 
+    "addr:state": "Ontario", 
+    "y": 45.413, 
+    "x": -75.691, 
+    "addr:country": "Canada"
+}
+```