List endpoint and 2.0 refactors(#11)

Geocodio · Sep 20, 2024 · 195cc2a · 195cc2a
1 parent 1f55cb6
commit 195cc2a
Show file tree

Hide file tree

Showing 16 changed files with 1,061 additions and 228 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 All notable changes to `geocodio-library-php` will be documented in this file
 
+## 2.0 - TBD
+
+- Added support for list geocoding
+- Breaking: all method responses now return an associative array rather than a JSON decoded object
+- Breaking: Dropped support for unsupported PHP versions
+  - Minimum supported version of PHP is now 8.2
+
 ## 1.7.0 - 2024-09-02
 
 - Added support for the `format` parameter, thanks to pull request [#7](https://github.com/Geocodio/geocodio-library-php/pull/7) by [@kirilldakhniuk](https://github.com/kirilldakhniuk)

diff --git a/README.md b/README.md
@@ -11,6 +11,13 @@
   * [Field appends](#field-appends)
   * [Address components](#address-components)
   * [Limit results](#limit-results)
+  * [Uploading Lists](#uploading-lists)
+    + [Upload list from a file](#upload-list-from-a-file)
+    + [Upload list of inline data](#upload-list-of-inline-data)
+    + [List processing status](#list-processing-status)
+    + [Download a list](#download-a-list)
+    + [Fetch all uploaded lists](#fetch-all-uploaded-lists)
+    + [Delete uploaded list](#delete-uploaded-list)
 - [Usage with Laravel](#usage-with-laravel)
 - [Testing](#testing)
 - [Changelog](#changelog)
@@ -45,67 +52,45 @@ $geocoder->setApiKey('YOUR_API_KEY');
 $response = $geocoder->geocode('1109 N Highland St, Arlington, VA');
 dump($response);
 /*
-{
-  "input": {
-    "address_components": {
-      "number": "1109"                                                       
-      "predirectional": "N"                                                   
-      "street": "Highland"                                                   
-      "suffix": "St"                                                    
-      "formatted_street": "N Highland St"                                     
-      "city": "Arlington"                                                     
-      "state": "VA"                                                           
-      "country": "US"                                                         
-    }                                                                        
-    "formatted_address": "1109 N Highland St, Arlington, VA"                
-  }             
-  "results": array:2 [                                                         
-    0 => {
-      "address_components": {
-        "number": "1109"                                                       
-        "predirectional": "N"
-        "street": "Highland"   
-        "suffix": "St"
-        "formatted_street": "N Highland St"
-        "city": "Arlington"
-        "county": "Arlington County"
-        "state": "VA"
-        "zip": "22201"
-        "country": "US"
-      }
-      "formatted_address": "1109 N Highland St, Arlington, VA 22201"
-      "location": {
-        "lat": 38.886672
-        "lng": -77.094735
-      }
-      "accuracy": 1
-      "accuracy_type": "rooftop"
-      "source": "Arlington"
-    }
-    1 => {
-      "address_components": {
-        "number": "1109"
-        "predirectional": "N"
-        "street": "Highland"
-        "suffix": "St"
-        "formatted_street": "N Highland St"
-        "city": "Arlington"
-        "county": "Arlington County"
-        "state": "VA"
-        "zip": "22201"
-        "country": "US"
-      }
-      "formatted_address": "1109 N Highland St, Arlington, VA 22201"
-      "location": {
-        "lat": 38.886665
-        "lng": -77.094733
-      }
-      "accuracy": 1
-      "accuracy_type": "rooftop"
-      "source": "Virginia Geographic Information Network (VGIN)"
-    }
+array:2 [
+  "input" => array:2 [
+    "address_components" => array:8 [
+      "number" => "1109"
+      "predirectional" => "N"
+      "street" => "Highland"
+      "suffix" => "St"
+      "formatted_street" => "N Highland St"
+      "city" => "Arlington"
+      "state" => "VA"
+      "country" => "US"
+    ]
+    "formatted_address" => "1109 N Highland St, Arlington, VA"
   ]
-}
+  "results" => array:1 [
+    0 => array:6 [
+      "address_components" => array:10 [
+        "number" => "1109"
+        "predirectional" => "N"
+        "street" => "Highland"
+        "suffix" => "St"
+        "formatted_street" => "N Highland St"
+        "city" => "Arlington"
+        "county" => "Arlington County"
+        "state" => "VA"
+        "zip" => "22201"
+        "country" => "US"
+      ]
+      "formatted_address" => "1109 N Highland St, Arlington, VA 22201"
+      "location" => array:2 [
+        "lat" => 38.886672
+        "lng" => -77.094735
+      ]
+      "accuracy" => 1
+      "accuracy_type" => "rooftop"
+      "source" => "Arlington"
+    ]
+  ]
+]
 */
 
 $response = $geocoder->reverse('38.9002898,-76.9990361');
@@ -201,6 +186,144 @@ $response = $geocoder->geocode('1109 N Highland St, Arlington, VA', [], 1); // O
 $response = $geocoder->reverse('38.9002898,-76.9990361', ['timezone'], 5); // Return up to 5 geocoding results
 ```
 
+### Uploading Lists
+
+The lists API lets you upload and process spreadsheet with addresses or coordinates. Similar to the spreadsheet feature in the dashboard, the spreadsheet will be processed as a job on Geocodio's infrastructure and can be downloaded at a later time. While a spreadsheet is being processed it is possible to query the status and progress.
+
+> [!IMPORTANT]
+> Data for spreadsheets processed through the lists API are automatically deleted 72 hours after they have finished processing. In addition to a 1GB file size limit, we recommend a maximum of 10M lookups per list batch. Larger batches should be split up into multiple list jobs.
+
+See the [API docs for geocoding lists](https://www.geocod.io/docs/#geocoding-lists) for additional details.
+
+#### Upload list from a file
+Creates a new spreadsheet list job and starts processing the list in the background. The response returns a list id that can be used to retrieve the job progress as well as download the processed list when it has completed.
+
+```php
+$response = $geocoder->uploadList(
+    file: 'path/to/file.csv',
+    direction: GeocodeDirection::Forward,
+    format: '{{B}} {{C}} {{D}} {{E}}',
+    callbackWebhook: 'https://example.com/callbacks/list-upload',
+);
+
+/*
+array:2 [
+  "id" => 11953719
+  "file" => array:3 [
+    "headers" => array:5 [
+      0 => "Name"
+      1 => "Address"
+      2 => "City"
+      3 => "State"
+      4 => "Zip"
+    ]
+    "estimated_rows_count" => 4
+    "filename" => "simple.csv"
+  ]
+]
+*/
+```
+
+#### Upload list of inline data
+
+```php
+$csvData = <<<'CSV'
+name,street,city,state,zip
+"Peregrine Espresso","660 Pennsylvania Ave SE",Washington,DC,20003
+"Lot 38 Espresso Bar","1001 2nd St SE",Washington,DC,20003
+CSV;
+
+$geocodio->uploadInlineList(
+    $csvData,
+    'coffee-shops.csv',
+    GeocodeDirection::Forward,
+    '{{B}} {{C}} {{D}} {{E}}'
+);
+```
+
+#### List status
+View the metadata and status for a single uploaded list.
+
+```php
+$geocoder->listStatus(11950669);
+
+/*
+array:6 [
+  "id" => 11953719
+  "fields" => []
+  "file" => array:2 [
+    "estimated_rows_count" => 4
+    "filename" => "simple.csv"
+  ]
+  "status" => array:5 [
+    "state" => "COMPLETED"
+    "progress" => 100
+    "message" => "Completed"
+    "time_left_description" => null
+    "time_left_seconds" => null
+  ]
+  "download_url" => "https://api.geocod.io/v1.7/lists/11953719/download"
+  "expires_at" => "2024-09-22T20:36:10.000000Z"
+]
+*/
+```
+
+#### Download a list
+Download a fully geocoded list, the returned format will always be a UTF-8 encoded, comma-separated csv file.
+
+```php
+$geocoder->downloadList(11950669, 'path/to/file.csv');
+```
+
+#### Fetch all uploaded lists
+Show all lists that have been created. The endpoint is paginated, showing 15 lists at a time, ordered by recency.
+
+```php
+$geocoder->lists();
+
+/*
+array:9 [
+  "current_page" => 1
+  "data" => array:1 [
+    0 => array:6 [
+      "id" => 11953719
+      "fields" => []
+      "file" => array:2 [
+        "estimated_rows_count" => 4
+        "filename" => "simple.csv"
+      ]
+      "status" => array:5 [
+        "state" => "COMPLETED"
+        "progress" => 100
+        "message" => "Completed"
+        "time_left_description" => null
+        "time_left_seconds" => null
+      ]
+      "download_url" => "https://api.geocod.io/v1.7/lists/11953719/download"
+      "expires_at" => "2024-09-22T20:36:10.000000Z"
+    ]
+  "first_page_url" => "https://api.geocod.io/v1.7/lists?page=1"
+  "from" => 1
+  "next_page_url" => null
+  "path" => "https://api.geocod.io/v1.7/lists"
+  "per_page" => 15
+  "prev_page_url" => null
+  "to" => 3
+]
+*/
+```
+
+#### Delete uploaded list
+Delete a previously uploaded list and its underlying spreadsheet data permanently. This can also be used to cancel and delete a spreadsheet that is currently processing.
+
+Geocodio Unlimited customers can cancel a spreadsheet at any time. Pay as You Go customers can only cancel a spreadsheet if it was just recently started.
+
+The spreadsheet data will always be deleted automatically after 72 hours if it is not deleted manually first.
+
+```php
+$geocoder->deleteList(11950669);
+```
+
 ## Usage with Laravel
 
 This library works well without Laravel, but if you happen to be using Laravel you can enjoy a few Laravel-specific features.

diff --git a/bin/git-hooks/formatting b/bin/git-hooks/formatting
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+_print() {
+    printf "\e[38;5;4m%s\e[0m\n" "$1"
+}
+
+main() {
+    files_before_format=$(git diff --name-only --diff-filter=d)
+
+    _print "Running pint..."
+    vendor/bin/pint --dirty
+
+    _print "Running rector..."
+    vendor/bin/rector process --no-diffs
+
+    files_after_format=$(git diff --name-only --diff-filter=d)
+
+    # Find files fixed by pint by comparing file lists before and after pint run
+    files_fixed_by_format=$(comm -13 <(sort <<<"$files_before_format") <(sort <<<"$files_after_format"))
+
+    # Re-stage files fixed by pint
+    _print "Re-staging changed files..."
+    for f in $files_fixed_by_format; do git add "$f"; done || exit
+}
+
+main "$@"