{"id":18369175,"url":"https://github.com/ideal-postcodes/jquery.postcodes","last_synced_at":"2025-04-06T17:31:59.582Z","repository":{"id":9689913,"uuid":"11636912","full_name":"ideal-postcodes/jquery.postcodes","owner":"ideal-postcodes","description":"jQuery plugin to quickly add postcode lookups on a form using Royal Mails Postcode Address File","archived":false,"fork":false,"pushed_at":"2021-05-09T18:45:10.000Z","size":1103,"stargazers_count":21,"open_issues_count":5,"forks_count":11,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-02T23:35:19.341Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ideal-postcodes.co.uk/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ideal-postcodes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-24T14:35:10.000Z","updated_at":"2023-08-06T19:02:19.000Z","dependencies_parsed_at":"2022-09-11T10:50:54.960Z","dependency_job_id":null,"html_url":"https://github.com/ideal-postcodes/jquery.postcodes","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fjquery.postcodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fjquery.postcodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fjquery.postcodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fjquery.postcodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ideal-postcodes","download_url":"https://codeload.github.com/ideal-postcodes/jquery.postcodes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522458,"owners_count":20952555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T23:28:39.597Z","updated_at":"2025-04-06T17:31:58.438Z","avatar_url":"https://github.com/ideal-postcodes.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **January 2021** jquery.postcodes has moved (and no longer requires jQuery). Please see our new [Postcode Lookup](https://github.com/ideal-postcodes/postcode-lookup) library\n\n# UK Postcode Lookup jQuery Plugin\n\nAdd UK address lookups with a simple postcode input field on any web form with the Ideal-Postcodes.co.uk API. Ideal Postcodes uses Royal Mail's addressing database, the Postcode Address File (PAF).\n\n[![CircleCI](https://circleci.com/gh/ideal-postcodes/jquery.postcodes/tree/master.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/jquery.postcodes/tree/master)\n\nPAF is licensed from the Royal Mail and incurs a license fee per lookup. We make PAF available to the public at **2p** per [external](https://ideal-postcodes.co.uk/termsandconditions#external) lookup.\n\n## How it Works\n\nThis plugin creates an input field to lookup postcodes on the Ideal Postcodes API. If your user searches a valid postcode, a dropdown menu is displayed and the selected address is piped into appropriate fields.\n\nThe plugin provides addresses according to [Royal Mail's Addressing Guidelines](http://www.royalmail.com/personal/help-and-support/How-do-I-address-my-mail-correctly). This consists of 3 address lines, a Post Town and Postcode and is sufficient to uniquely identify a premise in the UK.\n\n![Ideal Postcodes Plugin Example](https://raw.github.com/ideal-postcodes/jquery.postcodes/master/examples/ideal_postcodes_snippet.png)\n\n## Getting Started\n1) **[Download the plugin](https://raw.github.com/ideal-postcodes/jquery.postcodes/master/dist/postcodes.min.js)** and add to your page\n\n```html\n\u003cscript src=\"jquery.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"jquery.postcodes.min.js\"\u003e\u003c/script\u003e\n```\n\n2) **[Sign up](https://ideal-postcodes.co.uk)** to get an API key\n\n3) **Setup a Postcode Search Field** by inserting an empty div tag and calling `.setupPostcodeLookup()`. Pass in a configuration object identifying specifying your API Key and address fields (using CSS selectors)\n\n```html\n\u003cdiv id=\"postcode_lookup_field\"\u003e\u003c/div\u003e\n\u003cscript\u003e\n$('#postcode_lookup_field').setupPostcodeLookup({\n\t// Set your API key\n\tapi_key: 'iddqd',\n\t// Pass in CSS selectors pointing to your input fields to pipe the results\n\toutput_fields: {\n\t\tline_1: '#first_line',\n\t\tline_2: '#second_line',\n\t\tline_3: '#third_line',\n\t\tpost_town: '#post_town',\n\t\tpostcode: '#postcode'\n\t}\n});\n\u003c/script\u003e\n```\n\n## Documentation \u0026 Configuration\n\n[Latest documentation can be found at ideal-postcodes.co.uk](https://ideal-postcodes.co.uk/documentation/jquery-plugin)\n\nThis plugin also allows you to draw additional addressing information. The complete list of available data fields can be found [here](https://ideal-postcodes.co.uk/documentation/paf-data).\n\nThere are a lot of ways to configure the plugin to create an address lookup feature that suits most use cases. The documentation will guide you through how to use additional configuration options like customised styling, customised inputs \u0026 triggers, useful callbacks, key checking, etc.\n\nFor examples of the more advanced ways you can configure the plugin take a look at [ideal-postcodes.co.uk/jquery](https://ideal-postcodes.co.uk/jquery).\n\n## Testing\n\nRun automated tests with\n\n```\nnpm test\n```\n\nPlease use jQuery 1.9.x or higher. This plugin has been tested against jQuery 1.9.x, 1.10.x, 1.11.x, 2.0.x, 2.1.x, 2.2.x, 3.0.x. 3.1.x and 3.2.x\n\nYou may run the plugin locally and test in your browser\n\n```bash\n$ npm start # starts a HTTP server\n\n# Navigate to the `examples` folder and select an example in a *.html file\n```\n\nOur test postcodes are:\n- **ID1 1QD** Returns a successful postcode lookup response (2000)\n- **ID1 KFA** Returns \"postcode not found\" error (4040)\n- **ID1 CLIP** Returns \"no lookups remaining\" error (4020)\n- **ID1 CHOP** Returns \"daily (or individual) lookup limit breached\" error (4021)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fjquery.postcodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fideal-postcodes%2Fjquery.postcodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fjquery.postcodes/lists"}