librarieshacked/api-geography

API to provide useful geography data services for UK public library applications

Geography API

A Node JS API to provide common UK geography services for library applications.

Getting Started

These instructions will give you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Requirements for the software and other tools to build, test and push

• Node JS

Installing

Install the required packages

npm install

The project should then be able to be run locally by running

npm start

Authors

• Dave Rowe - Original code and maintenance - DaveBathnes

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT Licence

api-geography's Issues

Basic postcode routes Rest API

The database has database data in it so we can add some routes and a model to deal with postcode data. Initially this will be for the Rest API but will later also be included in a Graph QL API, and Mapbox Vector Tiles.

Acceptance Criteria

• Get a single postcode
• Get LSOA for many postcodes. Must filter by postcode sectors.

Create library authorities endpoint

We need an endpoint that provides just a list of library authorities, including:

• A very generalised outline
• A code
• An English name
• A Welsh name
• Area
• Bounding box

Use generalised geometry in the database for library authorities

The database now directly stores generalised geometries for ease of use in the database.

These should be used where possible and replaced with manually processed geometries.

Add Swagger endpoint

It would be useful for testing and documentation purposes to have a Swagger endpoint for the API.

LSOA vector tiles

To create LSOA browsing tools for deprivation and library membership there will need to be a vector tile API to provide LSOAs.

This will need to include:

• The tiles from the database
• The name of the LSOA

Acceptance Criteria

• LSOA vector tiles able to be displayed on a web map

LSOA tiles not working

Fix LSOA tiles

Add place names endpoint

We need an endpoint for autocomplete and retrieval of place names

Built up area tiles failing

The built up area tiles are failing with a code exception

Publish API

The API needs to be published online.

Acceptance Criteria

• API running and tested on Azure
• API uses domain name api-geography.librarydata.uk

Poor postcode lookup performance

After doing insensitive case matching the postcode lookup service has bombed. Indexing must not be working after doing lowercase processing.

Fix LSOA MVT route

Getting LSOAs is not working and also appears to be maxing out the database.

Fix authority name endpoint

The endpoint for authority name doesn't seem to be working

Isochrone service

OpenRouteService provides various APIs around routing:

• Directions
• Geocoding
• Isochrones
• Optimization

Ultimately these should be delivered using a routing database. But for now there is an API with free limits that we can use, and cache to ensure we do not call too many times.

To start off with, implement an isochrone service with 1 week caching based on a single input point.

Adjust to use authority official name and nice name

The database has been updated to hold an official name, as well as a 'nice' name for local authorities.

The library authority endpoints should use both of these.

Add get route by authority name

There should be a lookup option to get the authority by name.

Update to use the new database

An updated database includes column name changes, primarily to remove specific years (e.g. lad19cd to ladcd)

This requires various code changes to use the new names

Add postcode reverse geocoding endpoint

Add an endpoint to take coordinates and return postcode data for that location based upon postcode coordinates

Reduce complexity of library authorities GeoJSON

When retrieving all the library authorities the GeoJSON amounts to about 30MB. This is far too large!

Vector tiles

To create browsing tools we will need vector tile services for:

• Wards
• Regions
• Countries
• Library services

To start off, create the service for library authorities

Acceptance Criteria

• Vector tiles able to be displayed on a web map

Add endpoints for retrieving tiles on built up areas

The database will have built up areas added as vector tiles.

These need to be added to the API

Add LSOA GeoJson endpoint

Make an endpoint for LSOA GeoJson to support generating vector tiles

Add postcode search endpoint

Add an endpoint to allow postcode autocomplete with a max set of 50 results.

Add extra detail authority boundary

When we are calling to get an individual authority we should get extra detail for the authority boundary.

This can replace the existing generalised boundary field.

LSOA lookup not working

A recent refactor has meant the LSOA endpoint is no longer working

Remove geometry from library authorities

Including the geometry geojson in the library authorities response by default makes the request too large. This should be optional, and then included on individual service responses, also as an option.

Add option to retrieve library services in order of proximity to a location

For use in things like the library book search, it would be useful to have library service in order of proximity to a location.

As it is not point-to-point the actual distance will have to be the nearest point on the authority boundary. The API will need to provide the distance in shortest and longest distance away.

Performance of postcodes to LSOA

The postcodes to LSOA takes a long time. This includes:

• Call to the database
• Processing data
• Downloading the data

Acceptance Criteria

• Performance improved

Allow filtering of place names by type

Pass in the place name types to the place name endpoints in order to allow filtering

Make postcode case insensitive

When searching for a postcode, or providing postcode sectors we should always treat them as case-insensitive.

Acceptance Criteria

• Return a postcode using lower case and uppercase and a mix
• Return LSOAs using postcode sector with a mix of case

Timeout issues

The web request seems to be timing out when taking over a minute.

Acceptance Criteria

• Reason understood and fixed

Make fields optional

Put in a system so that the API endpoints can take in a comma-separated list of fields which are then the only fields returned from the data.

This should also modify the SQL query so that there is a real performance benefit to limiting the fields returned.