markembling/markembling.postcodesio

.NET library for interacting with the excellent Postcodes.io service.

MarkEmbling.PostcodesIO

.NET library for interacting with the excellent Postcodes.io service.

Usage

var client = new PostcodesIOClient();
var result = client.Lookup("GU1 1AA");
// result contains properties such as Latitude, Longitude, Region, County and so on...

Check out the integration tests (MarkEmbling.PostcodesIO.Tests) for further examples.

---

This library is still a work-in-progress. More examples and documentation will come soon, along with the missing API methods.

In the meantime, the package is available on NuGet:

PM> Install-Package MarkEmbling.PostcodesIO

Be aware: the API may fluctuate until it hits v1.0. But I think it's already going down the right path, so we're probably fine for the most part. But as always, use at your own risk.

Contributions

Feel free to make contributions via a pull request. Please keep the tests current (and add, if necessary).

markembling.postcodesio's Issues

Poor testability without hitting live API

Right now, testing is pretty much reliant on hitting the live API in integration tests. This needs to change so all the independent bits of behaviour (e.g. deserialisation of results) does not depend on hitting the live API and hard-coding live data which may change over time.

May have an impact on the public API, so ideally would happen before v1.0.0.

Distance not included when using Nearest

I have noticed that when calling https://api.postcodes.io/postcodes/:postcode/nearest the distance is returned, however it is not returned when using Nearest(postcode) or NearestAsync(postcode)

I have forked your code to fix this, happy to create a PR if this is helpful?

Terminated postcodes aren't tested

The functionality for terminated postcode endpoints needs testing.

Abstract away inconsistency of empty results

Currently the API returns null for some query endpoints where no results/matches exist, and for others it returns []. This can't be changed for backwards-compatibility reasons (see ideal-postcodes/postcodes.io#319).

However it makes sense in the context of this client to abstract that away and handle empties in a more predictable way (i.e. always returning an empty IEnumerable<T>). This will be more consistent for devs using this client library. This will be a backwards-incompatible change, so needs to tie to v1.x.

The ability to opt out of normalising empty results and back into API-consistent behaviour (3a/3b in the linked discussion, where results will come back as null where the API gives that) should probably also be added.

RestSharp update breaks client.Lookup(Postcode)

Updating to latest RestSharp via Nuget breaks functionality. Latest RestSharp requires minimum of .Net 4.5.2

RestSharp update 106.5 breaks this package

See restsharp/RestSharp#1198

In PostcodesIO the following error occurs when RestSharp is upgraded from 106.4 to 106.5:

System.MissingMethodException: Method not found: 'Void RestSharp.RestRequest..ctor(System.String, RestSharp.Method)'.
at MarkEmbling.PostcodesIO.PostcodesIOClient.CreateLookupRequest(String postcode)
at MarkEmbling.PostcodesIO.PostcodesIOClient.LookupAsync(String postcode)

Fixed for me by downgrading RestSharp back to 106.4.2 (in case this helps others)

.NET 4.5 and async

Hi,

I forked your library and upgraded to .NET 4.5, as well as adding async methods for all the various REST endpoints. Would you like me to create separate versions so the current .NET 4.0 can still be targeted, or would you be happy if I created a pull request and the latest version dropped support for older .NET versions?

Thanks!

Issue with proxy/proxy Windows auth under .NET Core on Windows (.NET standard lib)

407 proxy authentication required: default system proxy and authentication seems to not be working as expected. Apparently a side-effect of using RestSharp on .NET Core rather than .NET Framework.

Needs more investigation.

Mark PostcodeResult as Serializable

Hi,

I have a very small feature request.

I'm using your library to interact with the postcodes.io API and I'm looking to add redis caching to my lookups to prevent any excessive API calls, ideally I would like to simply serialise the PostcodeResult. To easily do this it would be useful if the PostcodeResult class was marked as [Serializable].

Example on main page

In your example on the README.md you've got

var client = new PostcodesIOClient();
var result = _client.Lookup("GU1 1AA");

I think you mean client.Lookup rather than _client.Lookup

Move Execute methods out of PostcodesIOClient

Move these out so they can be swapped out for more testing without hitting a live API.

Also will prevent duplication for #11.

Split up methods on PostcodesIOClient

There are a massive (and growing, see #10) number of methods on PostcodesIOClient. These need to be split up in logical groups.

The best approach is probably to mirror the split from the Postcodes.io docs (postcodes, outcodes, terminated_postcodes, places).

Ced

Why is "ced" not available in PostcodeResult?

When we lookup ex. OX14 3PF we would like to use. "Abingdon East". When we use Postcodes.io website this is returned in ced, but the property is not included in PostcodeResult.

Check and test 404 responses

The Postcodes.io API will return a 404 response when querying for a postcode which doesn't exist (and so on across the various endpoints).

Ensure these are handled in an unsurprising, consistent way and that this is tested.

Missing API methods

Some API methods are missing and need to be added, including the entire /places API.

Test all fields on ReverseGeocodeQuery

Test that all fields are used correctly.

Same for bulk reverse geocoding.

Tests are all jumbled up

As the API has grown, the tests have become a bit of a mess. They all need tidying up and splitting up in a more logical way. Will depend on #10, #11 and probably #13.