Download the PHP package philcross/getaddress-php without Composer

getAddress PHP SDK

This is a framework agnostic PHP SDK for getAddress.io's address lookup API.

To use this package, you will need an API key provided by getAddress.io, the basic package is free. When you sign up, you will be given both a API key for accessing public address information, and an administrative API key for managing your account.

This package also relies on PHP 5.6

Installation

Installation is easily done via composer

Basic Usage

To begin, you will need both of your API keys provided by getAddress.io, then create the client:

There are a bunch of helpful methods on the client which will allow you to lookup addresses, and manage your account. The client will know which API key to use.

Looking up a public address

To lookup a public address you will need, at minimum, a postcode. You can also specify a property number, but this is optional. The find method will return an AddressResponse object. This contains an array of Address objects.

You can also supply a 3rd boolean argument to the find() method. By default, it will requests are returned by getAddress.io sorted numerically. If you don't want them sorted numerically, you can provide boolean false:

Using the Address Object

The address object has a few helpful methods on it:

There is also a getTown() method, but this is an alias of getCity():

To return the address as an associative array, you can use the toArray() method:

In addition, you can overwrite the keys of the array by providing an array to the toArray() method:

You can also convert the address to a comma seperate list of elements using the toString() method.

by default, the toString() method will not take out empty elements. This is useful to conver the address to a CSV record. If you want to format the address as a nice string, removing the empty elements:

One last helper is the sameAs() method, which accepts another Address object to compare. This will compare the address arrays to see if they're the same:

Checking your account usage

You can quickly check your account usage using the usage() method on the client.

If you don't provide any arguments, it will return the current usage for the day. The usage method will return a Usage object:

There are also a few extra helper methods. To check how many requests you have remaining, until you run out for the day:

You can also supply boolean true to the method to return the number of requests remaining until getAddress.io slows it's response down:

You can also check to see if you've exceeded your limit:

And one last one, you can check if you've made enough requests for getAddress.io to slow the responses down, but not enough to for them to stop sending responses.

If you want to retrieve your usage from a previous date, you can supply a DateTime object (or a Carbon instance) to the usage method:

Alternatively, you can supply the day month and year as parameters to the method:

Private Addresses

getAddress.io allows you to provide private addresses. These are addresses you supply, that are only available by using your API token.

Adding a new private address

You can add a new private address:

When you create a new private address, it will return a PrivateAddressResponse object, which contains a message provided by getAddress, and the new address you created as a PrivateAddress object:

The PrivateAddress object extends the Address object, so you can still use methods like sameAs() etc. The PrivateAddress object also contains a getAddressId() method, to return the ID of your private address record.

Deleting a private address

If you have the ID and postcode of a private address, you can delete it:

Again, this will return a PrivateAddressResponse object with a message.

Listing private addresses

You can list all private addresses you have for a specified postcode:

Or, if you know the ID of the property, you can supply the ID as well:

Security

getAddress allow you to whitelist domains and IP addresses.

Adding a domain or IP address to the whitelist

Both methods return a WhitelistResponse object, which have getMessage() and getItems() methods.

The getItems() method will always return an array full of either Domain objects, or Ip objects, but never a combination.

Both Domain and Ip objects have a getId() method to return the unique ID for that object. The Domain object contains a getDomain() method, while the Ip object contains a getIp() method.

Deleting an existing whitelisted item

Both methods will return a WhitelistResponse object.

Listing whitelisted domains or IP addresses

Each method also has a related singular version of the method name if you know the ID of the whitelisted item.

Webhooks

getAddress allows you to specify urls to use as webhooks when you reach your first limit.

Adding a new URL as a webhook

This will return a WebhookResponse object which contains a getMessage() method, and getHooks() method which returns an array of Webhook objects.

Each Webhook object contains a getWebhookId() method, and getWebhookUrl() method.

Deleting an existing hook

To delete an existing webhook, you need to provide the ID:

Listing all webhooks

You can list all webhooks using this method. It will return a WebhookResponse object like above.

Alternatively, you can use the singular version of the method to retrieve a single webhook by it's ID:

Handling errors

If there is an error returned from getAddress.io, an exception will be thrown specific to the error returned.

For any other 4xx or 5xx error, an Philcross\GetAddress\Exceptions\UnknownException exception wil be thrown instead.

Tests

This package comes with a set of php unit tests. To run them: