Fork me on GitHub

Sorting Office

A Sinatra app that takes a UK address string and attempts to parse it into its constituent parts.

Try it out!

Enter an address below, and click Submit

How to use

Simply POST your address string like so (using curl):

curl --data "address=10 Downing Street, London, SW1A 2AA" https://sorting-office.openaddressesuk.org/address

If you'd like to submit the address you're using to the OpenAddresses project, then set contribute=true like so:

curl --data "address=10 Downing Street, London, SW1A 2AA&contribute=true" https://sorting-office.openaddressesuk.org/address

Please make sure you check with your users first! And be sure not to violate others' intellectual property or privacy rights with your submission.

You'll get the following response in JSON format:

{
  "saon": null,
  "paon": "10",
  "street": {
    "name": "Downing Street",
    "url": "http://alpha.openaddressesuk.org/streets/PXxwpD"
  }
  "locality": null,
  "town": {
    "name": "London",
    "url": "https://alpha.openaddressesuk.org/towns/4194LO"
  }
  "postcode": {
    "name": "SW1A 2AA",
    "url": "https://alpha.openaddressesuk.org/postcodes/EMCYvD"
  }
  "provenance": {
    "activity": {
      "executed_at": "2015-01-21T16:18:32+00:00",
      "processing_scripts": "https://github.com/OpenAddressesUK/sorting_office",
      "derived_from": [
      {
        "type": "userInput",
        "input": "10 Downing Street, London, SW1A 2AA",
        "inputted_at": "2015-01-21T16:18:32+00:00",
        "processing_script": "https://github.com/OpenAddressesUK/sorting_office/tree/7dd23cb19709680646a20dddfeb18b53ea4346e2/lib/sorting_office/address.rb"
        },
        {
          "type": "Source",
          "urls": [
          "http://alpha.openaddressesuk.org/postcodes/Uxm2vc"
          ],
          "downloaded_at": "2015-01-21T16:18:32+00:00",
          "processing_script": "https://github.com/OpenAddressesUK/sorting_office/tree/7dd23cb19709680646a20dddfeb18b53ea4346e2/lib/models/postcode.rb"
          },
          {
            "type": "Source",
            "urls": [
            "http://alpha.openaddressesuk.org/towns/qyHZe2"
            ],
            "downloaded_at": "2015-01-21T16:18:32+00:00",
            "processing_script": "https://github.com/OpenAddressesUK/sorting_office/tree/7dd23cb19709680646a20dddfeb18b53ea4346e2/lib/models/town.rb"
            },
            {
              "type": "Source",
              "urls": [
              "http://alpha.openaddressesuk.org/streets/Gq5142"
              ],
              "downloaded_at": "2015-01-21T16:18:32+00:00",
              "processing_script": "https://github.com/OpenAddressesUK/sorting_office/tree/7dd23cb19709680646a20dddfeb18b53ea4346e2/lib/models/street.rb"
            }
            ]
          }
        }
      }

The only caveat is that you must provide a valid postcode with your request, otherwise the service won't be able to calculate the other address parts. If a postcode is missing or invalid, the service will return a 400 error code and the following JSON:

  {
    "error": "We couldn't detect a real postcode in your address. Please resubmit with a valid postcode."
  }

If you’d rather not see the provenance data, you can add noprov=true to your request, like so:

curl --data "address=10 Downing Street, London, SW1A 2AA&noprov=true" https://sorting-office.openaddressesuk.org/address

Using in a web application

If you'd like to use Sorting Office client-side in a web application, take a look at the code which powers the demo

Address format

The address format returned in the JSON closely mirrors the BS7666 standard for addresses. It contains the following fields where name is the name of the resource, and url is the Open Addresses URL for that resource:

We are considering how to evolve this format to suit the needs of our roadmap. You can comment on this feature here: https://github.com/OpenAddressesUK/roadmap/issues/66

Feedback

We know that there are lots of edge cases with addresses, and we know that we might not have caught 100% of them. If there's anything you notice, please let us know, or better still open a pull request to fix it!.

Who built this?

This was built by the team at OpenAddresses. To find out more, visit the project website.