peekgeo 1.1.5
Package for PeekGeo API service for lightning-fast, affordable, and simple geocoding
License: MIT
Keywords: python,geocoding,forward_geocoding,reverse_geocoding,radius,autocomplete

### **PeekGeo API geocoding**! 

There are a few geocoding APIs out there to choose from. However, **PeekGeo** tops them
all with the most accurate, affordable, and effective solution!  

Our package focuses on a pythonic and accessible means to geocode using
with python code. 

---

#### **SUPPORT**

We have multiple support channels that you can contact us on: 
- [Slack](https://join.slack.com/t/peekgeoworkspace/shared_invite/zt-vpc4vqdz-gd1j7J7Oj6Mlokn74KvZfw)
- Twitter

---

#### **NOTE**

PeekGeo is a commercial product created by PeekGeo Software Development. Authorized
API tokens are necessary for utilizing the *FastAPI-driven* endpoints. Registering such API tokens is possible on 
our [website](). 

&#8594; Check out our official documentation [here](https://docs.google.com/document/d/1pQ2NiONDzIjCViocdG2P9RwbJrJM1P02YSVYkUFTPiE/edit?usp=sharing)!

---

#### **QUICK START**

#### PeekGeo() module

The `PeekGeo(token: str)` module allows you to register your access token into the PeekGeo API which
then provides the base for all geocoding, density, and radius functions.

&#8594; Note: The PeekGeo API package undergoes constant development so changes in endpoints may occur. 

To `import` the PeekGeo package: 
```python
from peekgeo import peekgeo_api as pg
```

---

#### **TABLE OF CONTENTS**
 
Endpoint | Function
---------|----------
load_properties_api | load_radius()
convex_search | convex()
density_search | density()
reverse_geocode | reverse()
batch_reverse | batch_reverse()
geocode | forward()
batch_geocode | batch_forward()

---

#### API EXAMPLES

All coding examples to the PeekGeo API can be found below regarding usage and 
implementation.

&#8594; Note: The code examples could be modified by the principles established by the API
official documentation.

<details>
<summary>&#8595; load_radius()</summary>

- coordinate: _required_, indicates `center` of search
- radius: _required_, indicates `radius` of search
- reverse_param: _bool_, (indicates the reversal of the input coordinates)

##### Example(1)
```python
pg = PeekGeo(token)

result = pg.load_radius(
    [43.0961466, -77.6337776],
    100,
    reverse_param=False
)
```

</details>

<details>
<summary>&#8595; convex()</summary>

- coordinate_array: _required_, `edges` of polygon
- reverse_param: _bool_, (indicates the reversal of the input coordinates)

##### Example(2)
```python
pg = PeekGeo(token)

result = pg.convex(
    [[43.0961466, -77.6337776],
     [43.1018722, -77.6334654],
     [43.1010339, -77.6342459]],
    reverse_param=False
)
```

</details>

<details>
<summary>&#8595; density()</summary>

#### **Radius Load Density**: 

- unit_input: _str_, _required_
  * options: [km, mi, m, ft, yd]
- unit_output: _str_, _required_ 
  * options: [km, mi, m, ft, yd]
- coordinates: _list_, _optional_    
- reverse_param: _bool_, (indicates the reversal of the input coordinates)

##### Example(3)
```python
pg = PeekGeo(token)
result = pg.density(
    'ft',
    'ft',
    coordinates=[43.1010339, -77.6342459],
    radius=100
)
```

---

#### **Custom Density**:

- unit_input: _str_, _required_
  * options: [km, mi, m, ft, yd]
- unit_output: _str_, _required_ 
  * options: [km, mi, m, ft, yd]
- custom_option: _str_, _optional_
  * city
  * postcode
  * region/state
- custom_utility: _Union[str, int]_, _optional_, 
  * custom_utility specifies the input of `custom_option`

##### Example(4)
```python
pg = PeekGeo(token)
result = pg.density(
    'ft',
    'ft',
    custom_option='postcode',
    custom_utility=10580
)
```

</details>

<details>
<summary>&#8595; reverse()</summary>

- coordinate: _required_, geographic location of `POI` (Place Of Interest)
- radius: _optional_, radius of `error`
  * Default error radius is **10 ft**
- reverse_param: _bool_, (indicates the reversal of the input coordinates)

##### Example(5)
```python
pg = PeekGeo(token)
result = pg.reverse(
    [43.1017283, -77.6338936],
    10, 
    reverse_param=False
)
```

</details>

<details>
<summary>&#8595; batch_reverse()</summary>

- coordinates: _required_, geographic location(s) of `POI` (Place Of Interest)
- radius: _optional_, radius of `error`
  * Default error radius is **10 ft**
- reverse_param: _bool_, (indicates the reversal of the input coordinates)

##### Example(6)
```python
pg = PeekGeo(token)
result = pg.batch_reverse(
    [[43.1017283, -77.6338985],
    [43.0936914, -77.6349024],
    [43.0937299, -77.6350315],
    [43.0930091, -77.6354702],
    [43.09245, -77.6353749]],
    10,
    reverse_param=False
)
```

</details>

<details>
<summary>&#8595; forward()</summary>

#### **Full Address Geocoding**

- full address: _optional_, formatted address of `POI` (Place Of Interest)
- unit: _str_, (the apartment `unit` of the full address if not provided)

##### Example(7)
```python
pg = PeekGeo(token)
result = pg.forward(
    "94 Crittenden Way, Brighton, NY, 14623",
)
```

#### **Parsed Address Geocoding**

- street: _optional_, `street` that POI is on
- number: _optional_, `number` on that street
- postcode: _optional_, `zip code` or `microregion` of the POI
- region: _optional_, `state` in the **USA** or `region` internationally
- city: _optional_, `city` where the POI is located
- unit: _optional_, `unit` if the property is classified as an apartment

##### Example (8.1) **without** unit
```python
pg = PeekGeo(token)
result = pg.forward(
    street="Crittenden Way",
    number=94,
    postcode=14623,
    region="NY",
    city="Brighton",
)
```

##### Example (8.2) **with** unit
```python
pg = PeekGeo(token)
result = pg.forward(
    street="Crittenden Way",
    number=88,
    postcode=14623,
    region="NY",
    city="Brighton",
    unit='Unit 2'
)
```

</details>

<details>
<summary>&#8595; batch_forward()</summary>

- addresses: _optional_, list of `formatted addresses`
- address_file: _optional_, `JSON` or `XML` file of formatted addresses
  * Note: Check documentation regarding formatting 

##### Example(9.1) **array** of addresses
```python
pg = PeekGeo(token)
result = pg.batch_forward(
    ["88 Crittenden Way, Brighton, NY, 14623, Unit 2",
     "140 Centre Drive, Brighton, NY, 14623",
     "94 Crittenden Way, Brighton, NY, 14623",
     "104 Crittenden Way, Brighton, NY, 14623, Unit 6"
     ]
)
```

##### Example(9.2) **file** of addresses

```python
pg = PeekGeo(token)
result = pg.batch_forward(
  address_file=address_file.json
)
```

```python
pg = PeekGeo(token)
result = pg.batch_forward(
  address_file=address_file.xml
)
```

&#8594; Download the [XML](https://github.com/MartinMashalov/PeekAPI/blob/package/analytics/address_file_XML.xml) or [JSON](https://github.com/MartinMashalov/PeekAPI/blob/okteto/analytics/test_spreadsheet_address.json) file as "address_file" to test the examples

</details>


---

#### INSTALLATION

Install `PeekGeo` on `pip`: 

```
$ pip install peekgeo
```

**OR**

Install `PeekGeo` on `conda`: 

```
$ conda install -c Martin Mashalov peekgeo
```

---

#### REQUIREMENTS

- [Python3](https://www.python.org/downloads/) >= 3.6
- [pymongo](https://pypi.org/project/pymongo/) >= 3.7.0
- [numpy](https://numpy.org/install/)
- [pandas](https://pandas.pydata.org/)

---

#### BUSINESS CONTACT

Our business email contact is: <hello@peekgeo.com>. Please feel free to reach out 
regarding any product feedback or support.