Test with a custom column name, plus README

Author: eyeseast

Diff for: Makefile

@@ -13,18 +13,21 @@ nominatim: tests/nominatim.db
 	geocode-sqlite nominatim $^ innout_test \
 		--location "{full}, {city}, {state} {postcode}" \
 		--delay 1 \
+		--raw \
 		--user-agent "geocode-sqlite"
 
 .PHONY: mapquest
 mapquest: tests/mapquest.db
 	geocode-sqlite open-mapquest $^ innout_test \
 		--location "{full}, {city}, {state} {postcode}" \
+		--raw \
 		--api-key "$(MAPQUEST_API_KEY)"
 
 .PHONY: google
 google: tests/google.db
 	geocode-sqlite googlev3 $^ innout_test \
 		--location "{full}, {city}, {state} {postcode}" \
+		--raw \
 		--api-key "$(GOOGLE_API_KEY)" \
 		--bbox 33.030551 -119.787326 34.695341 -115.832248
 
@@ -33,19 +36,23 @@ bing: tests/bing.db
 	geocode-sqlite bing $^ innout_test \
 		--location "{full}, {city}, {state} {postcode}" \
 		--delay 1 \
+		--raw \
 		--api-key "$(BING_API_KEY)"
 
 .PHONY: mapbox
 mapbox: tests/mapbox.db
 	geocode-sqlite mapbox $^ innout_test \
 		--location "{full}, {city}, {state} {postcode}" \
 		--delay 1 \
+		--raw \
 		--api-key "$(MAPBOX_API_KEY)"
 
 .PHONY: opencage
 opencage: tests/opencage.db
 	geocode-sqlite opencage $^ innout_test \
 		--location "{full}, {city}, {state} {postcode}" \
+		--delay '0.1' \
+		--raw \
 		--api-key "$(OPENCAGE_API_KEY)"
 
 .PHONY: run

Diff for: README.md

@@ -84,9 +84,30 @@ From there, we have a set of options passed to every geocoder:
 - `longitude`: longitude column name
 - `geojson`: store results as GeoJSON, instead of in latitude and longitude columns
 - `spatialite`: store results in a SpatiaLite geometry column, instead of in latitude and longitude columns
+- `raw`: store raw geocoding results in a JSON column
 
 Each geocoder takes additional, specific arguments beyond these, such as API keys. Again, [geopy's documentation](https://geopy.readthedocs.io/en/latest/#module-geopy.geocoders) is an excellent resource.
 
+## Using SpatiaLite
+
+The `--spatialite` flag will store results in a [geometry column](https://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/cookbook_topics.adminstration.html#topic_TABLE_to_SpatialTable), instead of `latitude` and `longitude` columns. This is useful if you're doing other GIS operations, such as using a [spatial index](https://www.gaia-gis.it/fossil/libspatialite/wiki?name=SpatialIndex). See the [SpatiaLite cookbook](https://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/index.html) and [functions list](https://www.gaia-gis.it/gaia-sins/spatialite-sql-latest.html) for more of what's possible.
+
+## Capturing additional geocoding data
+
+Geocoding services typically return more data than just coordinates. This might include accuracy, normalized addresses or other context. This can be captured using the `--raw` flag. By default, this will add a `raw` column and store the full geocoding response as JSON. If you want to rename that column, pass a value, like `--raw custom_raw`.
+
+The shape of this response object will vary between services. You can query specific values using [SQLite's built-in JSON functions](https://www.sqlite.org/json1.html). For example, this will work with Google's geocoder:
+
+```sql
+select
+  json_extract(raw, '$.formatted_address') as address,
+  json_extract(raw, '$.geometry.location_type') as location_type
+from
+  innout_test
+```
+
+Check each geocoding service's documentation for what's included in the response.
+
 ## Python API
 
 The command line interface aims to support the most common options for each geocoder. For more find-grained control, use the Python API.

Diff for: setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup
 import os
 
-VERSION = "0.7.0"
+VERSION = "0.8.0"
 
 requirements = ["click>=7.0", "sqlite_utils", "geopy"]
 

Diff for: tests/test_geocode_sqlite.py

@@ -426,3 +426,44 @@ def test_capture_raw(db, db_path, geocoder):
         result = geo_table.get(row["id"])
 
         assert raw == result
+
+
+def test_capture_raw_custom(db, db_path, geocoder):
+    table = db[TABLE_NAME]
+    geo_table = db[GEO_TABLE]
+
+    RAW = "raw_custom"
+
+    assert "latitude" not in table.columns_dict
+    assert "longitude" not in table.columns_dict
+    assert RAW not in table.columns_dict
+
+    # run the cli with our test geocoder
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "test",  # geocoder subcommand
+            str(db_path),  # db
+            str(TABLE_NAME),  # table
+            "--db-path",  # path, for test geocoder
+            str(db_path),
+            "--location",  # location
+            "{id}",
+            "--delay",  # delay
+            "0",
+            "--raw",
+            RAW,  # capture raw output with a custom name
+        ],
+    )
+
+    print(result.stdout)
+    assert 0 == result.exit_code
+
+    for row in table.rows:
+        assert type(row.get(RAW)) == str
+
+        raw = json.loads(row[RAW])
+        result = geo_table.get(row["id"])
+
+        assert raw == result