{"id":18369176,"url":"https://github.com/ideal-postcodes/ideal-postcodes-ruby","last_synced_at":"2025-04-06T17:31:59.449Z","repository":{"id":10170141,"uuid":"12253786","full_name":"ideal-postcodes/ideal-postcodes-ruby","owner":"ideal-postcodes","description":"UK postcode lookup API using Royal Mail's Postcode Address File.   ","archived":false,"fork":false,"pushed_at":"2021-11-18T07:58:21.000Z","size":86,"stargazers_count":12,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T23:35:19.387Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ideal-postcodes.co.uk","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","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":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-20T20:45:40.000Z","updated_at":"2022-12-16T18:48:29.000Z","dependencies_parsed_at":"2022-09-13T21:50:37.649Z","dependency_job_id":null,"html_url":"https://github.com/ideal-postcodes/ideal-postcodes-ruby","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fideal-postcodes-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fideal-postcodes-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fideal-postcodes-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fideal-postcodes-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ideal-postcodes","download_url":"https://codeload.github.com/ideal-postcodes/ideal-postcodes-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522460,"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.855Z","updated_at":"2025-04-06T17:31:59.095Z","avatar_url":"https://github.com/ideal-postcodes.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ideal Postcodes Ruby Library [![Build Status](https://travis-ci.org/ideal-postcodes/ideal-postcodes-ruby.png)](https://travis-ci.org/ideal-postcodes/ideal-postcodes-ruby)\n\nIdeal Postcodes is a simple JSON API to query UK postcodes and addresses. Find out more at [Ideal-Postcodes.co.uk](https://ideal-postcodes.co.uk/)\n\nOur API uses Royal Mail's Postcode Address File and is updated daily. Each method incurs a small charge (typically 2p) - free methods are labelled as such and are based on open data sources.\n\n## Getting Started\n\n**Install**\n\n```bash\ngem install ideal_postcodes\n```\n\nAlternatively, include this in your gemfile and bundle install\n\n```ruby\ngem 'ideal_postcodes'\n```\n\n**Create a Key**\n\nSign up at [Ideal-Postcodes.co.uk](https://ideal-postcodes.co.uk) and create a key.\n\n**Configure**\n\nDrop in your key when using the library.\n\n```ruby\nIdealPostcodes.api_key = \"your_key_goes_here\"\n```\n\n## Error Handling\n\nIt's important that you lookout for common exceptions when interacting with the API. The most common exceptions can be caught as shown below.\n\n```ruby\nbegin\n  IdealPostcodes::Postcode.lookup \"ID1 1QD\"\nrescue IdealPostcodes::AuthenticationError =\u003e e\n\t# Invalid API Key\nrescue IdealPostcodes::TokenExhaustedError =\u003e e\n\t# Token has run out of lookups\nrescue IdealPostcodes::LimitReachedError =\u003e e\n\t# One of your predefinied limits has been reached\nrescue IdealPostcodes::IdealPostcodesError =\u003e e\n\t# API Error\nrescue =\u003e e\n\t# An unexpected error\nend\n```\n\nPossible errors to look out for are listed in the [documentation](https://ideal-postcodes.co.uk/documentation/response-codes).\n\n## Methods\n\nThe client provides a number of methods to allow you to get specific jobs done quickly and easily. These methods are listed below.\n\n\n\n\n## Get all addresses for a postcode [(docs)](https://ideal-postcodes.co.uk/documentation/postcodes#postcode)\n\n```\nIdealPostcodes::Postcode.lookup postcode\n```\n\nReturns an array of addresses representing all addresses at the specified postcode.\n\n**Arguments**\n\n- `postcode` (string). The postcode you want to lookup, case and space insensitive.\n\n**Returns**\n\nAn array of hashes which represent each address at the postcode. Returns an empty array for an invalid postcode.\n\n**Example**\n\n```ruby\naddresses = IdealPostcodes::Postcode.lookup \"ID1 1QD\"\n\nif addresses.empty? \n\tputs \"Your postcode doesn't have a match\"\nelse\n\tputs addresses\nend\n\n# addresses =\u003e\n#[\n#  {\n#   :postcode =\u003e \"ID1 1QD\",\n#   :post_town =\u003e \"LONDON\",\n#   :line_1 =\u003e \"Kingsley Hall\",\n#   :line_2 =\u003e \"Powis Road\",\n#   :line_3 =\u003e \"\",\n#   :organisation_name =\u003e \"\",\n#   :building_name =\u003e \"Kingsley Hall\",\n#   :udprn =\u003e 12345678\n#   ... and so on\n```\n\n**Notes**\n\n**Data Source:** Royal Mail Postcode Address File. Ordnance Survey.\n\nUse the postcode \"ID1 1QD\" to test this method for free. The complete list of test postcodes is available in the [documentation](https://ideal-postcodes/documentation/postcodes).\n\n\n\n\n## Search for an address [(docs)](https://ideal-postcodes.co.uk/documentation/addresses#query)\n\nPerform a search for addresses which match your search term.\n\n```ruby\nIdealPostcodes::Address.search search_term, limit: 20, page: 0\n```\n\n**Arguments**\n\n- `search_term` (string). The address you wish to search for\n- `options` (hash, optional). Customise your search. \n\t- `limit` (number). The maximum number of returned results per page\n\t-\t`page` (number). Page of results to return (starts at page 0)\n\n**Returns**\n\nReturns a search result object with the following attributes.\n\n- `addresses` (Array). An array of hashes which represent each address at the postcode. The array is ordered by how close the search term and address match.\n- `limit` (Number). The maximum number of returned results per page.\n- `page` (Number). The returned page of results.\n\n\n**Example**\n\n```ruby\nIdealPostcodes::Address.search \"10 Downing Street London\"\n\nr.limit # =\u003e 10\nr.page  # =\u003e 0\nr.addresses\n\n#[\n#  {\n#    :line_1=\u003e\"Prime Minister \u0026 First Lord Of The Treasury\", \n#    :line_2=\u003e\"10 Downing Street\", \n#    :line_3=\u003e\"\", \n#    :post_town=\u003e\"LONDON\",  \n#    :postcode=\u003e\"SW1A 2AA\", \n#    :organisation_name=\u003e\"Prime Minister \u0026 First Lord Of The Treasury\", \n#    :premise=\u003e\"10\", \n#    :latitude=\u003e51.5035398826274\n#    :longitude=\u003e-0.127695242183412, \n#    :thoroughfare=\u003e\"Downing Street\", \n#    :district=\u003e\"Westminster\", \n#    :ward=\u003e\"St James's\", \n#    :building_number=\u003e\"10\", \n#    :udprn=\u003e23747771, \n#\t... and so on\n```\n\n**Notes**\n\nData source: Royal Mail Postcode Address File, Ordnance Survey.\n\nUse the address \"ID1 1QD\" to test integration for free. The complete list of test methods is available in the [documentation](https://ideal-postcodes/documentation/addresses).\n\n\n\n\n## Get nearby postcode for a given geolocation [(docs)](https://ideal-postcodes.co.uk/documentation/postcodes#lonlat)\n\nRetrieve the nearest postcodes for a given geolocation. Free to use.\n\n```ruby\nIdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat\n```\n\n**Arguments**\n\n- `location` (Hash)\n\t- `longitude` (number, required)\n\t- `latitude` (number, required)\n\t- `limit` (number, optional) Maximum number of results to return \n\t- `radius` (number, optional) search radius (in metres)\n\n**Returns**\n\nAn array of hashes which represent the nearest postcodes to the specified location. Ordered by distance from location.\n\n**Example**\n\n```ruby\npostcodes = IdealPostcodes::Postcode.find_by_location longitude: 0.629834, latitude: 51.79232\n\n# postcodes =\u003e\n#[\n#  {\n#    :postcode=\u003e\"CM8 1EF\", \n#    :northings=\u003e213679, \n#    :eastings=\u003e581461, \n#    :longitude=\u003e0.629834723775309, \n#    :latitude=\u003e51.7923246977375, \n#    :distance=\u003e0.52506633}, \n#  {\n#    :postcode=\u003e\"CM8 1EU\", \n#    :northings=\u003e213650, \n#    :eastings=\u003e581507, \n#    :longitude=\u003e0.630485817275861, \n#    :latitude=\u003e51.7920493205979, \n#    :distance=\u003e54.12525282\n#  },\n```\n\n**Notes**\n\nData source: Ordnance Survey. Free to use.\n\n\n\n## Retrieve an address using UDPRN [(docs)](https://ideal-postcodes.co.uk/documentation/addresses#address)\n\nRetrieve the specific address for a specific UDPRN.\n\n```ruby\nIdealPostcodes::Address.lookup udprn\n```\n\n**Arguments**\n\n- `udprn` (string | number). A number which uniquely identifies the address.\n\n**Returns**\n\nReturns a hash representing the matching address. Returns `nil` if no matching address is found.\n\n**Example**\n\n```ruby\nIdealPostcodes::Address.lookup 23747771\n\n#{\n#  :line_1=\u003e\"Prime Minister \u0026 First Lord Of The Treasury\", \n#  :line_2=\u003e\"10 Downing Street\", \n#  :line_3=\u003e\"\", \n#  :post_town=\u003e\"LONDON\",  \n#  :postcode=\u003e\"SW1A 2AA\", \n#  :organisation_name=\u003e\"Prime Minister \u0026 First Lord Of The Treasury\", \n#  :premise=\u003e\"10\", \n#  :latitude=\u003e51.5035398826274\n#  :longitude=\u003e-0.127695242183412, \n#  :thoroughfare=\u003e\"Downing Street\", \n#  :district=\u003e\"Westminster\", \n#  :ward=\u003e\"St James's\", \n#  :building_number=\u003e\"10\", \n#  :udprn=\u003e23747771, \n#  ... and so on\n```\n\n**Notes**\n\nData source: Royal Mail Postcode Address File, Ordnance Survey.\n\nUse the address `0` to test integration for free. The complete list of test methods is available in the [documentation](https://ideal-postcodes/documentation/addresses).\n\n## Utility Methods\n\nListed below are free utility methods, e.g. finding the status of your key.\n\n### Find out if your key is in a usable state [(docs)](https://ideal-postcodes.co.uk/documentation/keys#key)\n\nFind out if your key is in a usable state. E.g. it has a positive balance, it is currently under your defined usage limits, etc.\n\n```\nIdealPostcodes.key_available\n```\n\n**Arguments**\n\nNone.\n\n**Returns**\n\n- availability (Boolean). Returns true if key can be used. False if something is preventing the key from making lookups e.g. insufficient balance, reached limits, etc.\n\n**Example**\n\n```ruby\nIdealPostcodes.key_available # =\u003e true, you're clear to make lookups\n```\n\n### Retrieve private key information [(docs)](https://ideal-postcodes.co.uk/documentation/keys#details)\n\nThis method reveals private information about your key such as the lookup balance, whitelisted URLs, etc. Note: a secret key is required to invoke this method.\n\n```\nIdealPostcodes.key_details\n```\n\n**Arguments**\n\nNone.\n\n**Returns**\n\nReturns a hash containing pertinent private information about your key.\n\n**Example**\n\n```ruby\nIdealPostcodes.key_details\n\n# {\n# \t:lookups_remaining=\u003e9678, \n# \t:daily_limit=\u003e{\n# \t\t:limit=\u003e100, \n# \t\t:consumed=\u003e1\n# \t}, \n# \t:individual_limit=\u003e{\n# \t\t:limit=\u003e15\n# \t}, \n# \t:allowed_urls=\u003e[\"foo.com\"], \n# \t:notifications=\u003e{\n# \t\t:emails=\u003e[\"bar@baz.com\"], \n# \t:enabled=\u003etrue}, \n# \t:automated_topups=\u003e{\n# \t\t:enabled=\u003etrue\n# \t}\n# }\n```\n\nIf you intend to use this method, you must pass your secret key (which can be found on your [account page](https://ideal-postcodes.co.uk/account)) along with your API key when instantiating the client. E.g.\n\n```ruby\nIdealPostcodes.apply_secret \"your secret key\"\n```\n\nDo not share your secret key and avoid commiting this key to your codebase.\n\n## Testing\n\n```\nbundle exec rake\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fideal-postcodes-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fideal-postcodes%2Fideal-postcodes-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fideal-postcodes-ruby/lists"}