Skip to content

Commit 8c3b2b0

Browse files
docmarionum1docmarionum1
committed
readme
1 parent 5245aa3 commit 8c3b2b0

3 files changed

Lines changed: 150 additions & 91 deletions

File tree

‎README.md‎

Lines changed: 142 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,173 @@
11
# python-geosupport
22

3-
A Python library for geocoding with NYC Planning's [Geosupport Desktop Edition](https://www1.nyc.gov/site/planning/data-maps/open-data/dwn-gde-home.page).
3+
Python bindings for NYC Planning's [Geosupport Desktop Edition](https://www1.nyc.gov/site/planning/data-maps/open-data/dwn-gde-home.page).
44

55

6-
## Getting Started
6+
## Installation
77
### Prerequisites
88

9-
Install Geosupport Desktop Edition (v 18b):
9+
Install Geosupport Desktop Edition (tested with version 18b):
1010

1111
* [Geosupport Desktop Edition for Windows (32-bit)](http://www1.nyc.gov/assets/planning/download/zip/data-maps/open-data/gde_18b.zip)
1212
* [Geosupport Desktop Edition for Windows (64-bit)](http://www1.nyc.gov/assets/planning/download/zip/data-maps/open-data/gde64_18b.zip)
1313
* [Geosupport Desktop Edition for Linux](https://www1.nyc.gov/assets/planning/download/zip/data-maps/open-data/gdelx_18b.zip)
1414

15-
**Windows users:** Ensure you select the correct Geosupport installation that corresponds to the Python interpreter you are using. Ex., Python 32-bit will only work with Geosupport 32-bit.
15+
#### Windows
16+
**Important**: Ensure you select the correct Geosupport installation that corresponds to the Python interpreter you are using. Ex., Python 32-bit will only work with Geosupport 32-bit.
1617

1718
Additionally, you should check that the following environmental variables are set:
1819
* `GEOFILES` = the `fls` directory of your Geosupport installation. (ex. `C:\Program Files (x86)\Geosupport Desktop Edition\fls\`)
1920
* The Geosupport `bin` directory is in the `PATH`. (ex. `C:\Program Files (x86)\Geosupport Desktop Edition\bin`)
2021

21-
**Linux users:** Extract the .zip to a folder of your choice and set the `GEOFILES` and `LD_LIBRARY_PATH` environmental variables of the `fls` and `lib` directories like so:
22+
#### Linux
23+
Extract the .zip to a folder of your choice and set the `GEOFILES` and `LD_LIBRARY_PATH` environmental variables of the `fls` and `lib` directories:
2224

2325
```shell
2426
$ export GEOFILES=/var/geosupport/version-17c/fls
2527
$ export LD_LIBRARY_PATH=/var/geosupport/version-17c/lib/
2628
```
2729

28-
### How to use
29-
1. Install via [pip](https://pip.readthedocs.io/en/latest/quickstart.html):
30-
```python
31-
pip install python-geosupport
32-
```
33-
34-
2. Import the library and create an instance:
35-
```python
36-
from geosupport import Geocode
37-
38-
g = Geocode()
39-
```
40-
41-
3. Geocode with:
42-
43-
44-
**Street address** - [Function 1B](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-1b) (Must provide zip code or borough)
45-
```python
46-
result = g.address(house_number="125", street="Worth st", zip=10013)
47-
48-
result = g.address(house_number="125", street="Worth st", boro='MANHATTAN')
49-
```
50-
**Street address (single input)** - [Function 1B](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-1b) (Boro or zip is optional)
51-
```python
52-
result = g.address(address="125 Worth st, NY, NY")
53-
54-
result = g.address(address="125 Worth st", boro=1)
55-
```
56-
**Street address point** - [Function AP](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-ap) (Must provide zip code or borough)
57-
```python
58-
result = g.address_point(house_number="125", street="Worth st", zip=10013)
59-
60-
result = g.address_point(house_number="125", street="Worth st", boro="MANHATTAN")
61-
```
62-
**Borough, Block, and Lot** - [Function BL](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-bl)
63-
```python
64-
result = g.bbl(boro='1', block='00168', lot='0032')
65-
```
66-
**BIN** - [Function BN](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-bn)
67-
```python
68-
result = g.bin(bin='1001831')
69-
```
70-
**Placename** - [Function 1B](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-1b)
71-
```python
72-
result = g.place(place='VAN CRTLANDT MANSION', boro='bronx')
73-
```
74-
**Intersection** - [Function 2W](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-2-and-2w)
75-
```python
76-
result = g.intersection(street_1='ST NICHOLAS AVENUE', street_2='MENAHAN STREET', boro='QUEENS')
77-
```
78-
**Street Segment** - [Function 3](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-3)
79-
```python
80-
result = g.street_segment(on_street='STORY AVENUE',
81-
cross_street_1='EVERGREEN AVENUE',
82-
cross_street_2='WHEELER AVENUE',
83-
boro='BRONX')
84-
```
85-
**Blockface** - [Function 3C](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-3c)
86-
```python
87-
result = g.blockface(on_street='STORY AVENUE',
88-
cross_street_1='EVERGREEN AVENUE',
89-
cross_street_2='WHEELER AVENUE',
90-
boro='BRONX',
91-
compass_direction='N')
92-
```
93-
94-
**Street Stretch** [Function 3S](https://nycplanning.github.io/Geosupport-UPG/appendices/appendix01/#function-3s)
95-
```python
96-
result = g.street_stretch(on_street='CLIFTON PLACE',
97-
cross_street_1='SAINT JAMES PLACE',
98-
cross_street_2='GRAND AVENUE',
99-
boro='BK',
100-
compass_direction='N',
101-
compass_direction_2='S')
102-
```
103-
104-
*The `boro` argument can be borough code, borough name or a common borough abbreviation.
30+
### Install python-geosupport
31+
32+
Install via [pip](https://pip.readthedocs.io/en/latest/quickstart.html):
33+
34+
```shell
35+
$ pip install python-geosupport
36+
```
37+
38+
Or clone this repository and:
39+
40+
```shell
41+
$ python setup.py install
42+
```
43+
44+
## Usage
45+
46+
### Examples
47+
48+
#### Basic Usage
49+
50+
```python
51+
# Import the library and create a `Geosupport` object.
52+
from geosupport import Geosupport
53+
g = Geosupport()
54+
55+
# Call the address processing function by name
56+
result = g.address(house_number=125, street_name='Worth St', borough_code='Mn')
57+
```
58+
59+
`result` is a dictionary with the output from Geosupport. For example:
60+
61+
```
62+
{
63+
'2010 Census Block': '1012',
64+
'2010 Census Tract': '31',
65+
'Assembly District': '65',
66+
'Atomic Polygon': '112',
67+
'B10SC - First Borough and Street Code': '14549001010',
68+
'BOE Preferred B7SC': '14549001',
69+
'BOE Preferred Street Name': 'WORTH STREET',
70+
'BOROUGH BLOCK LOT (BBL)': {
71+
'BOROUGH BLOCK LOT (BBL)': '1001680032',
72+
'Borough Code': '1',
73+
'Tax Block': '00168',
74+
'Tax Lot': '0032'
75+
},
76+
'Blockface ID': '0212261942',
77+
...
78+
}
79+
```
80+
81+
#### Calling Geosupport functions
82+
83+
python-geosupport is flexible with how you call functions. You can use either
84+
Geosupport function codes or human readable alternate names, and access them
85+
either through python object attribute notation or dictionary item notation:
86+
87+
```python
88+
# Different ways of calling function 3S which processes street stretches
89+
g.street_stretch(...)
90+
g['street_stretch'](...)
91+
g['3S'](...)
92+
g.call({'function': '3S', ...})
93+
g.call(function='3S', ...)
94+
```
95+
96+
You can pass arguments as a dictionary, keyword arguments.
97+
98+
```python
99+
# Use a dictionary with short names
100+
g.street_stretch({'borough_code': 'MN', 'on': '1 Av', 'from': '1 st', 'to': '2 st'})
101+
# Use keyword arguments with short names
102+
g.street_stretch(
103+
borough_code='MN', street_name_1='1 Av',
104+
street_name_2='1 st', street_name_3='9 st'
105+
)
106+
# Use dictionary with full names
107+
g.street_stretch({
108+
'Borough Code-1': 'MN',
109+
'Street Name-1': '1 Av',
110+
'Street Name-2': '1 st',
111+
'Street Name-3': '9 st'
112+
})
113+
```
114+
115+
#### Mode
116+
117+
A number of Geosupport functions support several modes: Exetended, Long, and
118+
TPAD Long. You can set the flags individually as you would with using Geosupport
119+
directly, but python-geosupport makes it easier with the `mode` argument. `mode`
120+
can be one of `regular` (default), `extended`, `long` and `long+tpad`.
121+
122+
```python
123+
# Call BL (Block and Lot) function in long mode
124+
g.BL(mode='long', ...)
125+
g.BL(mode='long+tpad', ...) # With TPAD
126+
127+
# Call 3 (Street Segment) function in extended mode
128+
g.street_segment(mode='extended', ...)
129+
```
130+
131+
#### Interactive Help
132+
133+
Full function help can be viewed by calling `g.help()`.
134+
135+
```python
136+
# View an overview of all the functions available:
137+
g.help()
138+
139+
# View help for an individual function including a description, inputs, outputs,
140+
# and valid modes.
141+
g.address.help()
142+
g.help('address')
143+
144+
# View a list of all possible inputs to Geosupport
145+
g.help('input')
146+
```
147+
148+
## Development
105149

106150
### Running tests
151+
```shell
152+
$ python setup.py test
107153
```
108-
>> python setup.py test
154+
155+
Installing the dev dependencies (`nosetests` and `invoke`) will give you more
156+
control over running tests. Install in develop mode with dev dependencies with:
157+
158+
```shell
159+
$ pip install -e .[dev]
160+
```
161+
162+
And then run tests with:
163+
164+
```shell
165+
$ invoke test unit
166+
$ invoke test functional
167+
$ invoke test all
109168
```
110169

111-
### Known Issues
112-
* The single address input is experimental and subject to issues. Contributions to this feature are welcome.
113170

114-
### TODO
115-
* Improve single address input parsing
116-
* Better data with compass direction for testing `blockface` and `street_stretch` methods.
117171

118172
## License
119173

‎geosupport/function_info.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ def list_functions():
8787
" # Call address using the alternate name.\n"
8888
" g.address(house_number=125, street_name='Worth St', borough_code='Mn')\n"
8989
" # Call function 3 using the function code.\n"
90-
" g['3']({'borough_code': 'MN', 'on': '1 Av', 'from': '1 st', 'to': '2 st'})\n"
90+
" g['3']({'borough_code': 'MN', 'on': '1 Av', 'from': '1 st', 'to': '9 st'})\n"
9191
"\nUse Geosupport.help(<function>) or Geosupport.<function>.help() "
9292
"to read about specific function."
9393
)

‎setup.py‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
""",
3030
author='Ian Shiland',
3131
author_email='ishiland@gmail.com',
32-
packages=['geosupport', 'geosupport/parsers'],
32+
packages=['geosupport', 'geosupport/function_info'],
3333
license='MIT',
3434
keywords = ['NYC', 'geocoder', 'python-geosupport', 'geosupport'],
3535
classifiers=[
@@ -46,5 +46,10 @@
4646
'Programming Language :: Python :: 3.6',
4747
],
4848
test_suite="tests",
49-
install_requires=[]
49+
extras_require={
50+
'dev': [
51+
'invoke',
52+
'nose'
53+
]
54+
}
5055
)

0 commit comments

Comments
 (0)