PHP code example of geocodio / geocodio-library-php

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

geocodio / geocodio-library-php example snippets

$geocoder = new Geocodio\Geocodio();
$geocoder->setApiKey('YOUR_API_KEY');
// $geocoder->setHostname('api-hipaa.geocod.io'); // optionally overwrite the API hostname

$response = $geocoder->geocode('1109 N Highland St, Arlington, VA');
dump($response);
/*
array:1 [
  "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_province" => "VA"
        "postal_code" => "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');
$response = $geocoder->reverse([38.9002898, -76.9990361]);

$response = $geocoder->geocode([
    '1109 N Highland St, Arlington VA',
    '525 University Ave, Toronto, ON, Canada',
    '4410 S Highway 17 92, Casselberry FL',
    '15000 NE 24th Street, Redmond WA',
    '17015 Walnut Grove Drive, Morgan Hill CA'
]);

$response = $geocoder->reverse([
    '35.9746000,-77.9658000',
    '32.8793700,-96.6303900',
    '33.8337100,-117.8362320',
    '35.4171240,-80.6784760'
]);

// Optionally supply a custom key that will be returned along with results
$response = $geocoder->geocode([
    'MyId1' => '1109 N Highland St, Arlington VA',
    'MyId2' => '525 University Ave, Toronto, ON, Canada',
    'MyId3' => '4410 S Highway 17 92, Casselberry FL',
    'MyId4' => '15000 NE 24th Street, Redmond WA',
    'MyId5' => '17015 Walnut Grove Drive, Morgan Hill CA'
]);

$response = $geocoder->geocode(
    [
        '1109 N Highland St, Arlington VA',
        '525 University Ave, Toronto, ON, Canada'
    ],
    [
        'cd',
        'timezone'
    ]
);

$response = $geocoder->reverse('38.9002898,-76.9990361', ['census2010']);

$response = $geocoder->geocode([
    'street' => '1109 N Highland St',
    'city' => 'Arlington',
    'state_province' => 'VA',
    'postal_code' => '22201'
]);

$response = $geocoder->geocode([
    [
        'street' => '1109 N Highland St',
        'city' => 'Arlington',
        'state_province' => 'VA'
    ],
    [
        'street' => '525 University Ave',
        'city' => 'Toronto',
        'state_province' => 'ON',
        'country' => 'Canada',
    ],
);

$response = $geocoder->geocode('1109 N Highland St, Arlington, VA', [], 1); // Only get the first result
$response = $geocoder->reverse('38.9002898,-76.9990361', ['timezone'], 5); // Return up to 5 geocoding results

$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"
  ]
]
*/

$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}}'
);

$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/v2/lists/11953719/download"
  "expires_at" => "2025-08-22T20:36:10.000000Z"
]
*/

$geocoder->downloadList(11950669, 'path/to/file.csv');

$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/v2/lists/11953719/download"
      "expires_at" => "2025-08-22T20:36:10.000000Z"
    ]
  "first_page_url" => "https://api.geocod.io/v2/lists?page=1"
  "from" => 1
  "next_page_url" => null
  "path" => "https://api.geocod.io/v2/lists"
  "per_page" => 15
  "prev_page_url" => null
  "to" => 3
]
*/

$geocoder->deleteList(11950669);

// String format with ID
'37.7749,-122.4194,warehouse_1'

// Array format with ID
[37.7749, -122.4194, 'warehouse_1']

// The ID is returned in the response:
// [
//     'query' => '37.7749,-122.4194,warehouse_1',
//     'location' => [37.7749, -122.4194],
//     'id' => 'warehouse_1',
//     'distance_miles' => 3.2,
//     'distance_km' => 5.1
// ]

use Geocodio\Enums\DistanceMode;
use Geocodio\Enums\DistanceUnits;
use Geocodio\Enums\DistanceOrderBy;
use Geocodio\Enums\DistanceSortOrder;

// Available modes
DistanceMode::Straightline  // Default - great-circle (as the crow flies)
DistanceMode::Driving       // Road network routing with duration

// Available units
DistanceUnits::Miles  // Default
DistanceUnits::Km

// Sorting options
DistanceOrderBy::Distance  // Default
DistanceOrderBy::Duration

DistanceSortOrder::Asc   // Default
DistanceSortOrder::Desc

use Geocodio\Enums\DistanceMode;
use Geocodio\Enums\DistanceUnits;
use Geocodio\Enums\DistanceOrderBy;
use Geocodio\Enums\DistanceSortOrder;

// Geocode an address and calculate distances to store locations
$response = $geocoder->geocode(
    '1600 Pennsylvania Ave NW, Washington DC',
    destinations: [
        '38.9072,-77.0369,store_dc',
        '39.2904,-76.6122,store_baltimore',
        '39.9526,-75.1652,store_philly'
    ],
    distanceMode: DistanceMode::Driving,
    distanceUnits: DistanceUnits::Miles
);

/*
Response      ],
                [
                    'query' => '39.2904,-76.6122,store_baltimore',
                    'location' => [39.2904, -76.6122],
                    'id' => 'store_baltimore',
                    'distance_miles' => 38.2,
                    'distance_km' => 61.5,
                    'duration_seconds' => 2820
                ],
                // ...
            ]
        ]
    ]
]
*/

// Reverse geocode with distances
$response = $geocoder->reverse(
    query: '38.8977,-77.0365',
    destinations: [
        '38.9072,-77.0369,capitol',
        '38.8895,-77.0353,monument'
    ],
    distanceMode: DistanceMode::Straightline
);

// With filtering - find nearest 3 stores within 50 miles
$response = $geocoder->geocode(
    '1600 Pennsylvania Ave NW, Washington DC',
    destinations: [
        '38.9072,-77.0369,store_1',
        '39.2904,-76.6122,store_2',
        '39.9526,-75.1652,store_3',
        '40.7128,-74.0060,store_4'
    ],
    distanceMode: DistanceMode::Driving,
    distanceMaxResults: 3,
    distanceMaxDistance: 50.0,
    distanceOrderBy: DistanceOrderBy::Distance,
    distanceSortOrder: DistanceSortOrder::Asc
);

use Geocodio\Enums\DistanceMode;
use Geocodio\Enums\DistanceUnits;
use Geocodio\Enums\DistanceOrderBy;
use Geocodio\Enums\DistanceSortOrder;

// Calculate distances from one origin to multiple destinations
$response = $geocoder->distance(
    '37.7749,-122.4194,headquarters',  // Origin with ID
    [
        '37.7849,-122.4094,customer_a',
        '37.7949,-122.3994,customer_b',
        '37.8049,-122.4294,customer_c'
    ]
);

/*
Response:
[
    'origin' => [
        'query' => '37.7749,-122.4194,headquarters',
        'location' => [37.7749, -122.4194],
        'id' => 'headquarters'
    ],
    'destinations' => [
        [
            'query' => '37.7849,-122.4094,customer_a',
            'location' => [37.7849, -122.4094],
            'id' => 'customer_a',
            'distance_miles' => 0.9,
            'distance_km' => 1.4
        ],
        // ...
    ]
]
*/

// Use driving mode for road network routing (

use Geocodio\Enums\DistanceMode;
use Geocodio\Enums\DistanceUnits;
use Geocodio\Enums\DistanceOrderBy;
use Geocodio\Enums\DistanceSortOrder;

// Calculate full distance matrix with custom IDs
$response = $geocoder->distanceMatrix(
    origins: [
        '37.7749,-122.4194,warehouse_sf',
        '37.8049,-122.4294,warehouse_oak'
    ],
    destinations: [
        '37.7849,-122.4094,customer_1',
        '37.7949,-122.3994,customer_2'
    ]
);

/*
Response structure:
[
    'results' => [
        [
            'origin' => [
                'query' => '37.7749,-122.4194,warehouse_sf',
                'location' => [37.7749, -122.4194],
                'id' => 'warehouse_sf'
            ],
            'destinations' => [
                [
                    'query' => '37.7849,-122.4094,customer_1',
                    'location' => [37.7849, -122.4094],
                    'id' => 'customer_1',
                    'distance_miles' => 0.9,
                    'distance_km' => 1.4
                ],
                // ...
            ]
        ],
        [
            'origin' => [..., 'id' => 'warehouse_oak'],
            'destinations' => [...]
        ]
    ]
]
*/

// With driving mode and kilometers
$response = $geocoder->distanceMatrix(
    origins: ['37.7749,-122.4194'],
    destinations: ['37.7849,-122.4094'],
    mode: DistanceMode::Driving,
    units: DistanceUnits::Km
);

use Geocodio\Enums\DistanceMode;
use Geocodio\Enums\DistanceOrderBy;
use Geocodio\Enums\DistanceSortOrder;

// Find up to 2 nearest destinations from each origin
$response = $geocoder->distanceMatrix(
    origins: ['37.7749,-122.4194'],
    destinations: ['37.7849,-122.4094', '37.7949,-122.3994', '37.8049,-122.4294'],
    maxResults: 2
);

// Filter by maximum distance (in miles or km depending on units)
$response = $geocoder->distanceMatrix(
    origins: ['37.7749,-122.4194'],
    destinations: [...],
    maxDistance: 2.0
);

// Filter by minimum and maximum distance
$response = $geocoder->distanceMatrix(
    origins: ['37.7749,-122.4194'],
    destinations: [...],
    minDistance: 1.0,
    maxDistance: 10.0
);

// Filter by duration (seconds, driving mode only)
$response = $geocoder->distanceMatrix(
    origins: ['37.7749,-122.4194'],
    destinations: [...],
    mode: DistanceMode::Driving,
    maxDuration: 300,  // 5 minutes
    minDuration: 60    // 1 minute minimum
);

// Sort by duration descending
$response = $geocoder->distanceMatrix(
    origins: ['37.7749,-122.4194'],
    destinations: [...],
    mode: DistanceMode::Driving,
    maxResults: 5,
    orderBy: DistanceOrderBy::Duration,
    sortOrder: DistanceSortOrder::Desc
);

use Geocodio\Enums\DistanceMode;
use Geocodio\Enums\DistanceUnits;

// Create a new distance matrix job
$job = $geocoder->createDistanceMatrixJob(
    name: 'My Distance Calculation',
    origins: ['37.7749,-122.4194', '37.8049,-122.4294'],
    destinations: ['37.7849,-122.4094', '37.7949,-122.3994'],
    mode: DistanceMode::Driving,
    units: DistanceUnits::Miles,
    callbackUrl: 'https://example.com/webhook'  // Optional
);

// Or use list IDs from previously uploaded lists
$job = $geocoder->createDistanceMatrixJob(
    name: 'Distance from List',
    origins: 12345,       // List ID
    destinations: 67890,  // List ID
    mode: DistanceMode::Straightline
);

echo $job['id'];  // Job identifier

// Check job status
$status = $geocoder->distanceMatrixJobStatus($job['id']);
/*
[
    'id' => 'abc123',
    'name' => 'My Distance Calculation',
    'status' => [
        'state' => 'COMPLETED',  // or 'PROCESSING', 'FAILED'
        'progress' => 100,
        'message' => 'Completed'
    ],
    'download_url' => 'https://api.geocod.io/v2/distance-matrix/abc123/download',
    'expires_at' => '2025-01-15T12:00:00.000000Z'
]
*/

// List all jobs
$jobs = $geocoder->distanceMatrixJobs();
$jobs = $geocoder->distanceMatrixJobs(page: 2);  // Paginated

// Get job results as parsed array (same format as distance POST)
$results = $geocoder->getDistanceMatrixJobResults($job['id']);
/*
[
    'results' => [
        [
            'origin' => ['query' => '...', 'location' => [...], 'id' => '...'],
            'destinations' => [
                ['query' => '...', 'location' => [...], 'id' => '...', 'distance_miles' => 1.2, ...]
            ]
        ],
        // ...
    ]
]
*/

// Or download to file for very large results
$geocoder->downloadDistanceMatrixJob($job['id'], '/path/to/results.json');

// Delete a job
$geocoder->deleteDistanceMatrixJob($job['id']);

// Using facade
use Geocodio;

$response = Geocodio::geocode('1109 N Highland St, Arlington, VA');

// Using dependency injection
use Geocodio\Geocodio;

class SomeController {
  public function __construct(Geocodio $geocoder) {
      $response = $geocoder->geocode('1109 N Highland St, Arlington, VA');
  }
}

bash
composer 

php artisan vendor:publish --provider="Geocodio\GeocodioServiceProvider"