add similar street names example

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
   test-windows:
     runs-on: windows-latest
     env:
-      GEO_VERSION: 25a
+      GEO_VERSION: 25c
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3.11 (64-bit)
@@ -22,7 +22,7 @@ jobs:
         shell: pwsh
         run: |
           $FILENAME = "gde_${{ env.GEO_VERSION }}_x64.zip"
-          $URL = "https://s-media.nyc.gov/agencies/dcp/assets/files/zip/data-tools/bytes/$FILENAME"
+          $URL = "https://s-media.nyc.gov/agencies/dcp/assets/files/zip/data-tools/bytes/geosupport/$FILENAME"
           $LOCALDIR = "gde_${{ env.GEO_VERSION }}_x64"
           $TARGETDIR = "C:\Program Files\Geosupport Desktop Edition"
 
@@ -45,7 +45,7 @@ jobs:
   test-linux:
     runs-on: ubuntu-latest
     env:
-      GEO_VERSION: 25a
+      GEO_VERSION: 25c
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3.11
@@ -68,7 +68,7 @@ jobs:
 
           # Build the filename based on GEO_VERSION; for example, for 25b it becomes linux_geo25b_25.2.zip
           FILENAME="linux_geo${GEO_VERSION}_${NUM}.${MINOR}.zip"
-          URL="https://s-media.nyc.gov/agencies/dcp/assets/files/zip/data-tools/bytes/$FILENAME"
+          URL="https://s-media.nyc.gov/agencies/dcp/assets/files/zip/data-tools/bytes/geosupport/$FILENAME"
 
           LOCALDIR="geosupport-install-lx"
 

README.md

@@ -20,7 +20,7 @@ Check out documentation for installing and usage [here](https://python-geosuppor
 ## Compatibility
 
 - Python 3.8+
-- Tested on Geosupport Desktop Edition 25a
+- Tested on Geosupport Desktop Edition 25c
 - Windows (64-bit & 32-bit) and Linux operating systems
 
 ## Quickstart

examples/handle_similar_street_names.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+"""
+Example: Accessing similar street names from Geosupport errors
+
+When Geosupport can't find a street name, it returns up to 10 similar names
+in the error response. This example shows how to extract them.
+"""
+
+from geosupport import Geosupport, GeosupportError
+
+
+def get_similar_streets(error):
+    """Extract similar street names from a GeosupportError."""
+    result = error.result
+
+    # Get count of similar names (may be string or int)
+    count = result.get("Number of Street Codes and Street Names in List", 0)
+    if isinstance(count, str):
+        count = int(count.strip() or "0")
+    if count == 0:
+        return []
+
+    # Get list of street names (already parsed into a list by the library)
+    similar_names = result.get("List of Street Names", [])
+
+    # Filter out empty strings and return
+    return [name for name in similar_names if name and name.strip()]
+
+
+# Example usage
+if __name__ == "__main__":
+    g = Geosupport()
+
+    # Example 1: Misspelled street name
+    print("Example: Searching for 'wycoff street' in Brooklyn")
+    print("-" * 50)
+
+    try:
+        # This will fail because it should be 'wyckoff'
+        result = g["1N"](borough_code="BK", street_name="wycoff street")
+    except GeosupportError as e:
+        print(f"Error: {e}\n")
+
+        # Extract and display similar names
+        similar = get_similar_streets(e)
+        if similar:
+            print(f"Found {len(similar)} similar street(s):")
+            for i, name in enumerate(similar, 1):
+                print(f"  {i}. {name}")
+
+            # You could now retry with similar[0] or let user choose
+            print(f"\nRetrying with first match: '{similar[0]}'")
+            result = g["1N"](borough_code="BK", street_name=similar[0])
+            print(
+                f"Success! Street code: {result.get('B10SC - First Borough and Street Code')}"
+            )

examples/readme.md

@@ -1,23 +1,37 @@
 # Geosupport Examples
 
-Some examples to demonstrate different usages of python-geosupport. 
+Example scripts demonstrating python-geosupport usage.
+
+## Running Examples
+
+### Basic Usage
+
+```bash
+# Run any example directly
+python handle_similar_street_names.py
+python pandas_simple.py
+python pandas_multiprocessing.py
+```
+
+### Available Examples
+
+| Example | Description |
+|---------|-------------|
+| `handle_similar_street_names.py` | Extract similar street names when Geosupport returns a "NOT RECOGNIZED" error |
+| `pandas_simple.py` | Geocode addresses in a pandas DataFrame |
+| `pandas_multiprocessing.py` | Parallel geocoding using multiprocessing for large datasets |
 
 ## Using Docker
-Use NYC Plannings [docker-geosupport](https://github.com/NYCPlanning/docker-geosupport) image to geocode your data.
 
-> nycplanning/docker-geosupport image will be automatically updated whenever there's a new major release or upad release on Bytes of the Big Apple
+NYC Planning's [docker-geosupport](https://github.com/NYCPlanning/docker-geosupport) image includes python-geosupport pre-installed.
 
-### Build
-```shell
+```bash
+# Build the examples container
 docker build . -t geosupport-examples 
-```
 
-### Run
-From this directory, you can run: 
-```shell
+# Run examples
 docker run -it --rm --volume ${PWD}:/examples geosupport-examples pandas_simple.py 
-
 docker run -it --rm --volume ${PWD}:/examples geosupport-examples pandas_multiprocessing.py 
 ```
 
-The outputs will be in the *./data* directory. 
+Output files will be saved to `./data/` directory.