Metadata-Version: 2.4
Name: shw-geocoder
Version: 0.1.0
Summary: Geocoder client for SHSMI address_search API
Author: zx
License: MIT
Keywords: geocoder,geocoding,address,shsmi,csv
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# shw-geocoder

A minimal PyPI package that wraps the SHSMI `address_search` geocoding API. **THIS PACKAGE IS SPECIFIC TO CERTAIN GEOCODING APIS AND IS NOT UNIVERSAL.**

## Install

```bash
pip install shw-geocoder
```

For local development:

```bash
pip install -e .
```

## Python API

```python
from shw_geocoder import geocode

result = geocode("your-address", "geocoder-url")
print(result["data"][0]["pointX"], result["data"][0]["pointY"])
```

`geocode(address, base, result_count=3)` returns the raw JSON returned by the
service. When the address cannot be resolved, the payload's `count` field is `0`
and `data` is empty.

## CLI

The package exposes a `shw-geocoder` command.

### Single address

```bash
shw-geocoder --base "geocoder-url" \
             --address "your-address"
```

Prints `x, y, accuracy, poi, room_count` to stdout.

### Batch (CSV in -> CSV out + log)

```bash
shw-geocoder --base "geocoder-url" \
             --input  addrs.csv \
             --address-column address \
             --output out.csv \
             --log    run.log
```

- `out.csv` keeps every original column from `addrs.csv` and appends five new
  columns: `x, y, accuracy, poi, room_count`. Failed rows leave these blank.
- `run.log` is a plain-text summary containing start/end time, elapsed seconds,
  total / success / failed counts, and a breakdown by `accuracy` value.

### Arguments

| Flag              | Required | Description                                                  |
|-------------------|----------|--------------------------------------------------------------|
| `--base`          | yes      | Full URL of the address_search endpoint                      |
| `--input`         | batch    | Input CSV path                                               |
| `--address-column`| batch    | Column name in the input CSV that holds the address          |
| `--output`        | batch    | Output CSV path                                              |
| `--log`           | batch    | Log file path                                                |
| `--encoding`      | no       | Input CSV encoding (e.g. `utf-8`, `gbk`, `gb18030`); default `utf-8` |
| `--address`       | single   | Single address to geocode (printed to stdout)                |

`--address` and the `--input` group are mutually exclusive.
