Simple class to communicate with postcodeapi.nu

PostCodeApi.php

<?php
/**
 * Class PostcodeApi
 *
 * Simple PHP api class for http://www.postcodeapi.nu/
 */
class PostCodeApi
{
	/** @var string */
	protected $key;

	public $views = array(
		// http://api.postcodeapi.nu/docs/resources/bag
		'BAG' => 'bag',
	);

	/** Regex to match the zip code	 */
	const ZIP_CODE_REGEX = '^[0-9]{4}[ ]*[a-zA-Z]{0,2}$';
	/** The api url */
	const API_URL = 'http://api.postcodeapi.nu/';

	/**
	 * @param null|string $key
	 * @throws InvalidArgumentException
	 */
	public function __construct($key = null)
	{
		if(!is_null($key) && !is_string($key)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($key) . ' given');
		} elseif (!is_null($key)) {
			$this->key = $key;
		}
	}

	/**
	 * Returns the area data of the given zip code
	 *
	 * @param string $zip_code
	 * @return stdClass
	 * @throws InvalidArgumentException
	 * @throws Exception
	 */
	public function getArea($zip_code)
	{
		if (!is_string($zip_code)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($zip_code) . ' given');
		} elseif (!$this->isValidZipCode($zip_code)) {
			throw new \Exception('Invalid zip code is given, needs ' . self::ZIP_CODE_REGEX . ' format');
		}

		$zip_code = $this->filterZipCode($zip_code);
		return $this->request(self::API_URL . $zip_code . '?type=' . $this->getType($zip_code));
	}

	/**
	 * Returns the address data of the given zip code and the (house)number
	 *
	 * See http://api.postcodeapi.nu/docs/resources/housenumber for all the views and more info
	 *
	 * @param string $zip_code
	 * @param string|int $number
	 * @param null|string $view
	 * @return stdClass
	 * @throws InvalidArgumentException
	 * @throws Exception
	 */
	public function getAddress($zip_code, $number, $view = null)
	{
		if (!is_string($zip_code)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($zip_code) . ' given');
		} elseif (!$this->isValidZipCode($zip_code)) {
			throw new \Exception('Invalid zip code is given, needs ' . self::ZIP_CODE_REGEX . ' format');
		} elseif (!is_string($number) && !is_int($number)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string or int, except ' . gettype($number) . ' given');
		} elseif (!$this->isValidView($view)) {
			throw new \Exception('Invalid type given, see the views for valid types. Given: ' . $view);
		}

		$zip_code = $this->filterZipCode($zip_code);

		$url = self::API_URL . $zip_code . '/' . $number;
		$url .= ($view === null) ? '' : '?view=' . $view;

		return $this->request($url);
	}

	/**
	 * Returns the address data of the given latitude and longitude
	 *
	 * See http://api.postcodeapi.nu/docs/resources/wsg84 for all the views and more info
	 *
	 * @param string $latitude
	 * @param string $longitude
	 * @param null|string $view
	 * @return stdClass
	 * @throws InvalidArgumentException
	 */
	public function getByLatLng($latitude, $longitude, $view = null)
	{
		if (!is_string($latitude)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($latitude) . ' given');
		} elseif (!is_string($longitude)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($longitude) . ' given');
		} elseif (!is_null($view) && !is_string($view)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($view) . ' given');
		}

		$url = self::API_URL . 'wgs84/' . $latitude . '/' . $longitude;
		$url .= ($view === null) ? '' : '?view=' . $view;

		return $this->request($url);
	}

	/**
	 * Sets the api key value for PostcodeApi
	 *
	 * @param string $key
	 * @return PostcodeApi
	 */
	public function setKey($key)
	{
		$this->key = $key;
		return $this;
	}

	/**
	 * Returns the api ket
	 *
	 * @return string|null
	 */
	protected function getKey()
	{
		return $this->key;
	}

	/**
	 * Validates the zip code
	 *
	 * @param string $zip_code
	 * @return bool
	 * @throws InvalidArgumentException
	 */
	public function isValidZipCode($zip_code)
	{
		if (!is_string($zip_code)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($zip_code) . ' given');
		}

		return (1 === preg_match('~' . self::ZIP_CODE_REGEX . '~', $zip_code));
	}

	/**
	 * Validates the view
	 *
	 * See http://api.postcodeapi.nu/docs/resources/housenumber for all the views and more info
	 *
	 * @param string $view
	 * @return bool
	 * @throws InvalidArgumentException
	 */
	public function isValidView($view)
	{
		if (!is_string($view) && !is_null($view)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string or null, except ' . gettype($view) . ' given');
		}

		if (is_null($view)) {
			return true;
		}
		return in_array($view, $this->views);
	}

	/**
	 * Filters the zip code
	 * - removes spaces
	 * - uppercase charachters
	 *
	 * @param string $zip_code
	 * @return string
	 * @throws InvalidArgumentException
	 * @throws Exception
	 */
	protected function filterZipCode($zip_code)
	{
		if (!is_string($zip_code)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($zip_code) . ' given');
		} elseif (!$this->isValidZipCode($zip_code)) {
			throw new \Exception('Expected zip code format "' . self::ZIP_CODE_REGEX . '", ' . $zip_code . ' given');
		}

		return strtoupper(preg_replace('/\s+/', '', $zip_code));
	}

	/**
	 * See http://api.postcodeapi.nu/docs/overview/response for the response data
	 *
	 * @param string $url
	 * @return stdClass
	 * @throws InvalidArgumentException
	 * @throws Exception
	 */
	protected function request($url)
	{
		if (!is_string($url)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($url) . ' given');
		} elseif (!filter_var($url, FILTER_VALIDATE_URL)) {
			throw new \Exception('Given url is invalid');
		} elseif (!is_string($this->getKey())) {
			throw new \Exception('No api key given, so can\'t start the look up');
		}

		$ch = curl_init($url);
		curl_setopt_array( $ch, array(
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_HTTPHEADER => array(
				'Accept: */*',
				'Content-Type: application/x-www-form-urlencoded; charset=UTF-8',
				'Accept-Language: en',
				'Api-Key: ' . $this->getKey(),
			),
		));

		$json = json_decode(curl_exec($ch));
		if ($json === null) {
			return new stdClass();
		}
		return $json;
	}

	/**
	 * Returns the type of the given zip code
	 *
	 * See http://api.postcodeapi.nu/docs/resources/postcode what a types are available for the zip codes
	 *
	 * @param string $zip_code
	 * @return string
	 * @throws InvalidArgumentException
	 */
	protected function getType($zip_code)
	{
		if (!is_string($zip_code)) {
			throw new \InvalidArgumentException(__FUNCTION__ . ' expects string, except ' . gettype($zip_code) . ' given');
		}

		switch(strlen($zip_code)) {
			case 4:
				return 'p4';
				break;

			case 5:
				return 'p5';
				break;

			default:
				return 'p6';
		}
	}
}