A lightweight jQuery plugin that makes working with the Postcode API easy as pie.
More info, documentation and examples @ http://github.e-sites.nl/papi/
The Postcode API is developed by Freshheads. Check out the docs: http://api.postcodeapi.nu/docs/.
Well, for starters, because:
- it's lightweight (only 0.5kb minified w/ gzip) and developed with high performance in mind;
- it caches results internally, so no unecessary API calls;
- it validates the actual zipcode that is used to fetch the data;
- it handles responses internally so you can focus on processing the data in the available callbacks;
- it comes with a fully fledged static API (
$.papi
), so you can write your custom logic as well - it offers internal error handling (401, 404 and 500)
First download the plugin via Bower by running bower install papi
(or download it manually). Second, include the plugin as such (or lazy-load it):
<script src="jquery.min.js"></script>
<script src="jquery.papi.min.js"></script>
It's important you authorize yourself by setting the API key. Use the static .setApiKey
method for this:
$.papi.setApiKey('4815162342');
Basically, there are two routes you can follow. First, you can simply call the plugin on an element and pass some options. This way the whole process of fetching and handling the data will be done for you.
Also, you can use the static API to handle the data yourself, this gives you more freedom and possibilities.
Example plugin call:
$('#housenr').papi({
source: $('#zipcode4')[0],
event: 'change',
placeholders: {
street: $('#street4')[0],
town: $('#town4')[0]
}
});
Property | Type | Description |
---|---|---|
source
|
null |
When working with a house number this needs to point to the source element of the zipcode |
event
|
String |
Event type that triggers the actual lookup |
placeholders
|
Object |
The given and will be mapped against available properties that are returned by the API Available placeholders are: latitude, longitude, municipality, postcode, province, street, town, house_number, x, y, bag. |
bag
|
Boolean |
This will add an additional querystring (?view=bag ) to the call and will return BAG info (if available) |
Guess what, it sets the API key for authorization :-)
Initiates the actual GET
request to the API.
When all went good, this callback will be invoked.
The data will be available through the first argument. The this
context will point to the $.papi
object.
When no results are found, the API will return a 404 and this callback will be invoked.
Fills the given placeholder with available data
Fills all placeholders with available data.
Small helper to see if the given zipcode is valid
Tested in the latest versions of Google Chrome, Mozilla Firefox, Opera and Safari. As for Internet Explorer, it only works
in IE10+ due to the lack of proper CORS functionality. I have tried to work around this with XDomainRequest
, unfortunately
you can't set custom request headers
when using XDR, so authorization can't be realized.
Update: as from 0.3.0 I have included a PHP proxy to provide support for <IE10 as well.
Also, if you polyfill JSON.parse
/ JSON.stringify
and window.localStorage
you can support even IE7.
Copyright (C) 2015 E-sites, http://www.e-sites.nl/ Licensed under the MIT license.