homeserve-alliance/geocoder — pull request #2 by rob-murray (2014-05-28 10:10:44+00:00)
Title: Add postcode anywhere address validation

This is a slightly more controversial PR; it adds lookup classes for PostcodeAnywhere **Interactive Find** and **Interactive RetrieveById** services as used in homeserve-alliance/hsa-platform app.

These services are not true *Geocoding* services but rather Address verification, they do not return co-ordinates for any queries and as such they cannot be used to Geocode locations or reverse geocode points.

### Interactive Find ###

http://www.postcodeanywhere.co.uk/Support/WebService/PostcodeAnywhere/Interactive/Find/1.1/

This service returns a list of addresses for a given search term, each result includes a UDPRN (Unique Delivery Point Reference Number) that can be used with the Interactive RetrieveById service to fetch more information on that specific address.

```ruby
# List of addresses for postcode
results = Geocoder.search('N1 9AE', lookup: :postcode_anywhere_address)
```

A search for `LL11 5HJ` returns;

```json
[{"Id":"28692917.00","StreetAddress":"1 John Wilkinson Court","Place":"Brymbo Wrexham"},
{"Id":"28692918.00","StreetAddress":"2 John Wilkinson Court","Place":"Brymbo Wrexham"},
{"Id":"28692919.00","StreetAddress":"3 John Wilkinson Court","Place":"Brymbo Wrexham"}...
```

### Interactive RetrieveById ###

http://www.postcodeanywhere.co.uk/Support/WebService/PostcodeAnywhere/Interactive/RetrieveById/1.3/

This service returns detailed information for a UDPRN (Unique Delivery Point Reference Number) such as the full address so is usually used in conjunction with the above service

```ruby
# List of addresses for postcode, where is the fetch_id returned previously
results = Geocoder.search(50782641.00, lookup: :postcode_anywhere_address_fetch)

# or
results = Geocoder.search('N1 9AE', lookup: :postcode_anywhere_address)

# shortcut to above query
results.first.fetch
```

A request for the UDPRN `23747212.00` returns;

```json
[{"Udprn":"23747212","Company":"Buckingham Palace","Department":"","Line1":"","Line2":"","Line3":"","Line4":"","Line5":"","PostTown":"London","County":"","Postcode":"SW1A 1AA","Mailsort":"72114","Barcode":"(SW1A1AA1AL)","Type":"LargeBusiness","DeliveryPointSuffix":"1A","SubBuilding":"","BuildingName":"","BuildingNumber":"","PrimaryStreet":"","SecondaryStreet":"","DoubleDependentLocality":"","DependentLocality":"","PoBox":"","PrimaryStreetName":"","PrimaryStreetType":"","SecondaryStreetName":"","SecondaryStreetType":"","CountryName":"England","CountryISO2":"GB","CountryISO3":"GBR"}]
```

## Benefits of these additions ##

The benefits of fitting these square pegs into the Geocoder round hole are;

* A consistent API for performing location based queries.
* Lots of boilerplate request/response abstraction is taken care of.
* From hsa admin point of view, one API key can be used across the application
...