ziptastic / ziptastic-php

Official Ziptastic PHP Library

Ziptastic PHP

This library is a simple interface for the Ziptastic API.

Using Ziptastic requires an API key.

Installing

Ziptastic PHP can be installed via composer:

composer require ziptastic/ziptastic

Ziptastic PHP relies on HTTPlug to make API requests. HTTPlug is an abstraction which allows you to choose from any one of a large number of HTTP clients, including the client you might already have installed.

For more information on getting started with HTTPlug, please refer to the HTTPlug for library users documentation.

To just get moving right now, install a couple common dependencies:

composer require php-http/curl-client guzzlehttp/psr7 php-http/message

Usage

<?php

include "vendor/autoload.php";

use Ziptastic\Client;

$z = Client::create(getenv('ZIPTASTIC_API_KEY'));

Ziptastic provides two API methods: Lookup by a postal code (forward lookup), and lookup by latitude and longitude (reverse lookup).

$result = $z->forward(48038);
$result = $z->reverse(42.331427, -83.0457538, 1000);

Results are returned as a list of arrays:

<?php

$lookup = current($result);
echo $lookup['county']; // Macomb
echo $lookup['city']; // Clinton Township
echo $lookup['state']; // Michigan
echo $lookup['state_short']; // MI
echo $lookup['postal_code']; // 48038
echo $lookup['latitude']; // 42.5868882
echo $lookup['longitude']; // -82.9195514

// Timezones are represented by an instance of \DateTimeZone
echo $lookup['timezone']->getName(); // America/Detroit

PHP 5

If you require PHP 5 compatibility, please use Ziptastic-PHP version 1.

License

Ziptastic PHP is licensed under the MIT license.

ziptastic-php's Issues

Zipcode: 95531 returning empty timezone.

The zip code should return the UTC-8 (Pacific Time Zone) and UTC-7 (Pacific Daylight Time).

Guzzle?

So, I've been keeping an eye on this repo and I have been wondering why not use Guzzle instead of a custom curl client?

Reverse geocoding support

Hey @austinkregel and @jdpedrie, if you guys are game for this, it would be awesome to add reverse geocoding support to this.

I had thought before of making it a separate repo but it shouldn't add a whole lot to this I don't think.

The API endpoint is simply https://zip.getziptastic.com/v3/<latitude>/<longitude>, and it requires an API key just like the current forward geocoding endpoint.

Let me know what you think?

Differentiate failure cases

Invalid API key should not have the same result as an invalid zip code, etc.