Git Product home page Git Product logo

ordnancesurvey / osdatahub-js Goto Github PK

View Code? Open in Web Editor NEW
7.0 4.0 1.0 3.54 MB

A JavaScript package from Ordnance Survey, designed to make data from the OS Data Hub APIs readily accessible to developers.

Home Page: https://www.npmjs.com/package/osdatahub

License: Other

JavaScript 0.67% TypeScript 99.18% HTML 0.15%
api-wrapper geojson geospatial javascript nodejs ordnancesurvey osnames osplaces

osdatahub-js's Introduction

Tests Passing Node Version Browser Compatibility

Top Language Open Government License GitHub issues

osdatahub (JavaScript)

Coding in Python?
osdatahub has a sibling package for Python developers with similar functionality, check it out here.

osdatahub is a JavaScript package from Ordnance Survey (OS) that makes it easier to interact with the OS Data Hub APIs. The package helps you get started with our data in GeoJSON format, and rapidly build prototypes, test new ideas, or collect data for analyses.

Ordnance Survey is the national mapping agency for Great Britain and produces a large variety of mapping and geospatial products. Much of OS' data is available via the OS Data Hub, a platform that hosts both free and premium data products. osdatahub provides a user-friendly way to interact with these data products.

Ordnance Survey Logo

Links

Note: This package is under active development.

Contents

Supported APIs

osdatahub (JavaScript) supports the following Ordnance Survey APIs:

  • OS Names API
  • OS Places API
  • OS NGD Features API

Features

  • Access to Ordnance Survey data in 2 lines of code
    This wrapper abstracts the HTTP request process, so you can get to work on your geospatial project without configuring API endpoints.

  • Find features via geospatial and textual queries
    Use all available geospatial and textual search methods supported by each OS API to find and return data.

  • Request as much data as you need with automatic API paging
    By default, osdatahub will attempt to return a maximum of 1000 features. You can customise this by setting custom start (offset) and end (limit) values. Where multiple requests are required, osdatahub will merge these into a single response object. Please note that requesting a large amount of data may have cost implications.

  • Developer-Friendly GeoJSON Responses
    The osdatahub package exclusively uses GeoJSON and lng/lat (ESPG:4326) coordinates for returning data, please note that British National Grid coordinates (ESPG:27700) are not supported. You can use tools such as bboxfinder.com or geojson.io to collect input geometry for use in osdatahub. Responses from non-GeoJSON APIs are returned in specification-compliant GeoJSON format.

  • Pre- and Post- Request Error Handing
    osdatahub will handle some types of error prior to sending a request, such as invalid geometry, or a missing API key. Errors on the server (HTTP 5**/4** codes) are also handled.

Installation

You'll need to sign-up for an account on the OS Data Hub to create an API key:

  1. Navigate to the API Dashboard located on the top navigation bar
  2. Go to My Projects
  3. Click Create a new project, give your project a name, then click Create project
  4. Select Add an API to this project
  5. Choose the APIs you would like to use and click Done

NodeJS (via NPM)

Install the osdatahub package into your project, via NPM:

npm install osdatahub

You can then import osdatahub into your code:

// option 1 - import all the things (suggested)
import * as osdatahub from "osdatahub";
// option 2 - import specific modules
import { placesAPI } from "osdatahub";

Browser

Use directly in the browser with the following script tag:

<script src="https://unpkg.com/osdatahub/dist/bundle.min.js"></script>

Note: Be wary of exposing your OS Data Hub API key when running osdatahub in the browser!

You can find an example HTML page that uses the osdatahub-js package here [Source].

osdatahub browser demo

Getting Started

All osdatahub commands look something like this:

// Securely get API key (we recommend getting the key from environment variables/.env files)
const apiKey = process.env.OS_API_KEY

// querying the places API via bbox:
osdatahub.placesAPI.bbox(apiKey, [-1.4712, 50.9381, -1.4788, 50.9419], {
    limit: 200;
})

In the example above, we're querying the OS Places API using a Bounding Box (bbox), and we're specifying a maximum of 200 features should be returned (a total of two requests). Specifying a limit value is optional - optional parameters are stored within an object, which is passed in as the final parameter.

Different APIs support different search operations. Let's explore them...


OS NGD API

The OS NGD API can be accessed via osdatahub.ngd. For further information on using the OS NGD API and its capabilities, please refer to the OS Data Hub documentation and technical specification.

Features (Collection Items)

Get GeoJSON features from a specific product collection (e.g. Building Parts), using various parameter filters and/or geospatial filters

osdatahub.ngd.features(apiKey, collectionId, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • collectionId (string) - A valid collection ID e.g. (bld-fts-buildingpart)

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integer, default 100) - The maximum number of features to return
  • crs (string or number, default null) - CRS return GeoJSON [null defaults to WGS84]
  • bbox (array, default null) - Bounding-box [West, South, East, North] to search within (in ESPG:4326)
  • bboxCRS (string or number, default null) - CRS of bbox [null defaults to WGS84]
  • datetime (string, default null) - A valid date-time with UTC time zone (Z) or an open or closed interval. Only features that have a temporal geometry (versionavailablefromdate or versionavailabletodate) that intersects the value in the datetime parameter are selected. RFC 3339 Format
  • filter (string, default null) - Common Query Language (CQL) filter
  • filterCRS (string or number, default null) - CRS of filter if a spatial operation is used [null defaults to WGS84]

Feature (Single Collection Item)

Get a single GeoJSON feature from a specific product collection and feature Id

osdatahub.ngd.feature(apiKey, collectionId, featureId, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • collectionId (string) - A valid collection ID e.g. (bld-fts-buildingpart)
  • featureId (string) - A valid feature ID e.g. (00000016-e0a2-45ca-855a-645753d72716)

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • crs (string or number, default null) - CRS return GeoJSON [null defaults to WGS84]

Collections

Get information about a specific collection - if no collection ID is given function returns a list of all available collections!

osdatahub.ngd.collections(); // View all available collections
osdatahub.ngd.collections(collectionId); // Get info for specific collection

Parameters:

  • collectionId[Optional] (string) - A valid collection ID e.g. (bld-fts-buildingpart)

Schema

Get details of the feature attributes (properties) in a given collection

osdatahub.ngd.schema(collectionId);

Parameters:

  • collectionId (string) - A valid collection ID e.g. (bld-fts-buildingpart)

Queryables

Get all queryable attributes in a given collection

osdatahub.ngd.queryables(collectionId);

Parameters:

  • collectionId (string) - A valid collection ID e.g. (bld-fts-buildingpart)

OS Places API

The OS Places API can be accessed via osdatahub.placesAPI. For further information on using the OS Places API and its capabilities, please refer to the OS Data Hub documentation and technical specification.

GeoJSON Polygon

Returns all features within the geometry up to the user-defined limit.

osdatahub.placesAPI.polygon(apiKey, geoJson, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • geoJson (object) - Either a Feature or FeatureCollection as an object (in ESPG:4326)

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integrer, default 1,000) - The maximum number of features to return

Point-Based Radius

Returns all features within the geometry (user-defined distance from a point) up to the user-defined limit.

osdatahub.placesAPI.radius(apiKey, [lng, lat], searchRadius, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • [lng, lat] (array of numbers) - Point feature (in ESPG:4326)
  • searchRadius (number) - Distance (meters) to search around point (maximum 1,000)

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integrer, default 1,000) - The maximum number of features to return

Nearest Feature

Returns a single feature, the closest to the geometry (a point).

osdatahub.placesAPI.nearest(apiKey, [lng, lat], {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • [lng, lat] (array of numbers) - Point feature (in ESPG:4326)

Bounding Box

Returns all features within the bbox geometry (up to 1km2 in area), up to the user-defined limit.

osdatahub.placesAPI.bbox(apiKey, [b, b, o, x], {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • [b,b,o,x] (array of four numbers) - Bounding-box (West, South, East, North) to search within (in ESPG:4326)

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integrer, default 1,000) - The maximum number of features to return

UPRN (Unique Property Reference Number)

Returns a single feature, matching the input UPRN identifier.

osdatahub.placesAPI.uprn(apiKey, uprnIdentifer, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • uprnIdentifier (integer) - A valid UPRN identifer

Postcode (Full or Partial)

Returns features matching the input postcode. A full (e.g, SO16 0AS) or partial (e.g, OS16) postcode can be provided, the number of features returned (up to the user-defined limit) can vary considerably.

osdatahub.placesAPI.postcode(apiKey, postcode, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • postcode (string) - Full/Partial postcode to search in

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integrer, default 1,000) - The maximum number of features to return

Find (Plain Text Search)

Returns features matching the input text string provided. The number of features returned (up to the user-defined limit) can vary considerably.

osdatahub.placesAPI.find(apiKey, query, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • query (string) - A plain-text search string

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integrer, default 1,000) - The maximum number of features to return

OS Names API

The OS Names API can be accessed via osdatahub.namesAPI. For further information on using the OS Names API and its capabilities, please refer to the OS Data Hub documentation and technical specification.

Nearest Feature

Returns a single feature, the closest to the point geometry.

osdatahub.namesAPI.nearest(apiKey, [lng, lat], {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • [lng, lat] (array of numbers) - Point feature (in ESPG:4326)

Find (Plain Text Search)

Returns features matching the input text string provided. The number of features returned (up to the user-defined limit) can vary considerably.

osdatahub.namesAPI.find(apiKey, query, {});

Parameters:

  • apiKey (string) - Your OS Data Hub API Key
  • query (string) - A plain-text search string

Optional Parameters (add as named arguments e.g. {crs: 27700}):

  • offset (integer, default 0) - The starting position to collect features
  • limit (integrer, default 1,000) - The maximum number of features to return

Authors

The osdatahub (JavaScript) package has been built by:

Contribute

This package is still under active development and we welcome contributions from the community via issues and pull requests.

To install osdatahub, along with the tools you need to develop and run tests, run the following in your environment:

git clone https://github.com/OrdnanceSurvey/osdatahub-js.git
cd osdatahub-js
npm i

Support

For any kind of issues or suggestions please see the OS Data Hub documention, open a github issue or contact us via Email [email protected]

osdatahub-js's People

Contributors

abiddiscombe avatar abiddiscombe-os avatar dchirst avatar jepooley avatar jepooleyos avatar

Stargazers

avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar

Forkers

buildvoc

osdatahub-js's Issues

Enable Browser Usage

Provide a version of osdatahub for use in the web browser:

  1. Minify the codebase
  2. Use browser-native fetch capabilities, instead of node-fetch
  3. Distribute via CDN (?)

Feature collection filtering by properties with enumeration missing

Good afternoon

  1. Have deployed OS NGD API – Features Retrieve items from a feature collection, I noticed that https://labs.os.uk/public/osngd/os-ngd-api-features/examples/queryables.html has the filters built into query, how do I update my app to include these filters?
    image

  2. Where in the code do I change the location of bbox? (greyed out)
    image

Thanks for making code open source really helpful in development of building-height.co.uk
Building-Height is a system that can determine the attributes of historical buildings in England. The building part can be defined just by uploading a photo.
If you would like to try the app here is a link to an example image in Farnham, Surrey. (currently only have a couple thousand OS polygons footprints in our database for testing.

Spelling Errors in README.md

There are multiple instances of 'integrer' which should be 'integer' within the documentation.
Cases generally occur in the API examples section.

Outdated Tests: NGD FeatureType Spec Change

The test Collections Endpoint Passes w/ collectionId within ngd/ngd.test.js is failing due to updates to the NGD's schema. Whilst this has minimal impact on the user, the test is written to expect the old schema response (bld-fts-buildingline); this response will now be bld-fts-buildingline-1.

Fix 'total returned features' logged value

For queries that complete fully (total number of features is under the feature return limit), the total number of returned features appears to be incorrect (lower than expected). This could be due to either:

  1. The incorrect variable being passed as the final feature count,
  2. Failure to run the log command before the final page of results has been added to the temporary accumulated response object.

Add OS National Geographic Database Features API Support

Add functionality to integrate the OS NGD Features API:

  1. Add support for bbox spatial queries
  2. Provide capabilities to optionally pass a CQL filter to the API
  3. Provide efficient paging capability (via the links >> next component of the API response body) to the handler

API Key Compromised

Please advise on the use of the API key. Regardless of the application examples I find, the key is always embedded directly in the code in plain text. This is absolutely insecure, especially considering the fact that there is no way to restrict the key's actions by domain name.

How can the key be safely used in open systems? Is there a way to limit the key by domain name?

Outdated Screenshot in README.md

The media/browser_examples_screenshot.jpg references the old basemap tiles prior to the addition of the OS Maps API.
Let me know if you'd like me to update this 🙂

Change Basemap for JS example to Ordnance Survey

Currently, the osdatahub-js browser example uses OSM as the basemap. For consistency, change the basemap to the Ordnance Survey Maps API.

Be sure to use a locked down api key since it will be public

Code snippets in documentation incorrect

The following documentation corrections are required:

  1. (Installation) First import statement uses curly brackets, there are not required.
  2. (Getting Started) Example references a BBox but only provides two array components (a point feature)
  3. (Contribute) GitHub Issues href currently links to osdatahub-py

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.