geovision 0.1.7
Accurately geocode between coordinates, addresses and plus codes for any location on earth without an API-Key.
License: MIT
Requires Python: >=3.7

# GeoVision

Accurately geocode between coordinates, addresses and plus codes for ANY location on earth (whether it has a formal address or not) WITHOUT an API-Key.

<br/>

Made during [**DubHacks Autumn 2019**](https://dubhacks.co/)

## Installation

```
pip install geovision
```

A [Chrome Driver](https://chromedriver.chromium.org/) (Version 76) is also required and must be added to your system PATH. 


<br/>

Python has a lot of good geocoders, and most rely on external API keys to gather their data. The concept for this geocoder is somewhat the same, but also somewhat different than this philosophy. **Plus Codes** are one of the most recent additions to cartography. A Plus Code is like an address, but is different in that literally any location on earth has one. This makes them incredibly helpful and inclusive because people without an address can now indicate a legitimate place of residece. The website [plus.codes](https://plus.codes) features a map that allows you to search any location on earth for a plus code, address or coordinate. *GeoVision* takes advantage of this and uses this resource to make this information accessible to Python Programmers as an API. Some examples of Plus Codes are shown below.

<br/>

Location | Plus Code | Address | Coordinates
--- | --- | --- | ---
UW Smith Hall | 84VVMM4R+HX | 1911 Skagit Ln, Seattle, WA 98105, USA | 47.656437,-122.307563
Signal Iduna Park | 9F39FFV2+2P | Strobelallee 50, 44139 Dortmund, Germany | 51.492562,7.451812

<br/>

Because Plus Codes do not need an address, this Geocoder and go to many more places than most other ones. A prime example of this is buildings on University Campuses. There are often no streets in the middle of large University Campuses and therefore no street to give each building a unique address. Other geocoders may give you the same address for multiple buildings. *GeoVision*, however, easily tracks down these points to give you accurate information on coordinates and plus codes for even the most obscure places.

<br/>

*GeoVision* is not limited to broadly-termed keyword searches, you can also search for coordinates, plus codes and addresses to get the information you need from. 

## Note

Searching for a Country Name (i.e Germany), City Name (i.e Seattle) or any other excessively broad keyword will not yield any results other than perhaps some coordinates. There is a requisite level of specificity for *GeoVision* to work.

# Documentation

## `GeoVision`

`GeoVision` Objects hold all information for any location geocoded by the user. Information can easily be accessed individually or as a dictionary/list.

## `Geocoder`

`Geocoder` Objects can store GeoVision Objects for easy reference and management.

## `geocode`

`geocode` is a method that takes a string or a list of strings representing all the locations you'd like to search for as a parameter. Multi-Threading is included for better performance, so if you have many locations to geocode, pass that list into the `geocode` method rather than running `geocode` in a loop. The `geocode` method returns a `GeoVision` Object.

***

```python
# GeoVision Objects and geocode method
from geovision import geocode

# Get location data for 'Signal Iduna Park` in a GeoVision Object
g = geocode('Signal Iduna Park')

# geocode will return a list of GeoVision Objects. If only one location was
# passed in, a list of length 1 with the corresponding GeoVision Object will be returned.

g.locality # = Dortmund, Germany
g.country # = Germany
g.area_code # = 9F39
g.local_code # = FFV2+2P
g.plus_code # = 9F39FFV2+2P
g.address # = Strobelallee 50, 44139 Dortmund, Germany
g.coordinates # = (51.492562, 7.451812)
g.latitude # = 51.492562
g.longitude # = 7.451812
```

***

```python
# Geocoder Objects
from geovision import Geocoder

g = Geocoder()
g.geocode('Signal Iduna Park')
g.to_dict()
"""
{'Signal Iduna Park': {'locality': 'Dortmund, Germany', 'country': 'Germany', 'area_code': '9F39', 'local_code': 'FFV2+2P', 'plus_code': '9F39FFV2+2P', 'address': 'Strobelallee 50, 44139 Dortmund, Germany', 'coordinates': (51.492562, 7.451812), 'latitude': 51.492562, 'longitude': 7.451812}}
"""
```

# Dependencies

* [Python 3.7+](https://www.python.org/)
* [Selenium](https://www.seleniumhq.org/)
* [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)
* [Chrome Driver](https://chromedriver.chromium.org/)