Business Population Estimates - Application Programming Interface (API) instructions

About the API

The Application Programming Interface (API) allows advanced users to download headline data by entering a URL in a specific format. It is based on data from table 26 of the National Statistics output Business Population Estimates (BPE) 2017, which was published on 30 November 2017.

Please email business.statistics@beis.gov.uk should you have any feedback or comments.

Anatomy of an API request

The URL is made up of various elements:

http://njs.analysisoncbas.co.uk/business/bpe/emps_all_eb/E12000001?format=csv&year_start=2010&year_end=2017
hostroutetypequery

The host part is the address of the server on the internet.

The route represents the original data source, in this case Business Population Estimates.

The type section contains your data selection. You can have as many of these as you need, in any order. See below for further details - specifically, information from the id column requires entering.

The query section allows you to filter your selection of data, for instance by year. Parameters that control the output are also here, for instance file format or how the data are arranged. The complete list of parameters is also below.

Open each category by clicking the heading or icon.

Example usage is given below in the type example panels and query example panels

Type parameters

nameidno.
United KingdomUK1
North EastE120000012
North WestE120000023
Yorkshire and the HumberE120000034
East MidlandsE120000045
West MidlandsE120000056
East of EnglandE120000067
LondonE120000078
South EastE120000089
South WestE1200000910
EnglandE9200000111
WalesW9200000412
ScotlandS9200000313
Northern IrelandNI14
nameidno.
All private sector businessesemps_all_psb1
All employing businesses (1 or more)emps_all_eb2
With no employees (0)emps_none3
All small (0 to 49)emps_small4
All SME (0 to 249)emps_sme5
Micro (1 to 9)emps_1_96
Small (10 to 49)emps_10_497
Medium (50 to 249)emps_50_2498
Large (250 or more)emps_250_plus9

Generic API query parameters

The list of query parameters is appended to the very end of the URL after a single '?'. Each query parameter is separated from other query parameters with a single '&' character.

Allowable values are listed between '[' and ']', separated by '|'. The default value is given in bold (these will be used when no query parameter is specified).

  • type string
  • values [json | csv]
  • operation affects output
  • multiple items? no
  • type string
  • values [narrow | wide]
  • operation affects output data format/visual appearance
  • multiple items? no
  • type integer
  • minimum 2010
  • maximum 2017
  • default 2017
  • operation affects items selected
  • multiple items? no
  • type integer
  • minimum 1
  • default ALL
  • operation affects items selected
  • multiple items? no
  • type string
  • values [m | h | a]
  • description m machine-readable values; h human-friendly values; a all values
  • operation affects output data format/visual appearance
  • multiple items? no

Code examples

Here are some examples of how you might programmatically access the data using various programming languages.

The examples select the number of businesses with more than 250 employees in the South West and West Midlands, in 2017:
http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017

Javascript


// this assumes jQuery and/or d3 have been loaded and are available through $ or d3 variables (there are many other libraries that offer ajax support)

var URL_str = "http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017";

// 1.1 using jQuery Ajax, specifying csv in the header
$.ajax({url: URL_str, accepts: {csv: 'text/csv'}, dataType: 'text'}).done(function( data ) {
	console.log(data);
});

// 1.2 using jQuery convenience function for JSON (there isn't a corresponding CSV function)
$.getJSON( URL_str, function( data ) {
	console.log(data);
});


// 2. using d3 convenience function for CSV (there are also JSON and generic Ajax functions)
d3.csv(URL_str, function(error, data) {
	if (error) throw error;
	console.log(data);
}
				

Python


# this uses the requests package - there are other packages available for accessing http data
import requests

URL_str = "http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017"

# using requests
r = requests.get(URL_str, headers={"accept":"text/csv"})
print(r.text)  # basic output to console

# year,region_label,sizeband_label,value
# 2017,West Midlands,250 or more,600
# 2017,South West,250 or more,500

				

R


# this uses the httr library - there are other libraries available for accessing http data

library(httr)
library(readr)

URL_str <- "http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017"

csv <- GET(URL_str, accept("text/csv"))
content(csv) # uses readr to display data neatly with added metadata

# # A tibble: 2 x 4
#    year region_label  sizeband_label value
#                       
# 1  2017 West Midlands 250 or more      600
# 2  2017 South West    250 or more      500
				

Bash (Terminal commands in Unix/Linux/MacOS)


# remember to include entire URL in quotes, otherwise the '&' is interpreted as a line break

# this outputs to stdout (i.e. this console)
curl "http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017"
# year,region_label,sizeband_label,value
# 2017,West Midlands,250 or more,600
# 2017,South West,250 or more,500


# this outputs to a file called businesses_250_SW_WMid.csv

curl "http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017" -o businesses_250_SW_WMid.csv


# this outputs in wide orientation - the same query as above, but pivoted. 
# In this instance, human-readable style has also been used (style=h)

curl "http://localhost:8080/business/bpe/emps_250_plus/E12000005/E12000009?format=csv&year_start=2017&year_end=2017&orientation=wide&style=h"

# year,sizeband_label,South West,West Midlands
# 2017,250 or more,500,600

# and this outputs in json format
curl "http://njs.analysisoncbas.co.uk/business/bpe/emps_250_plus/E12000005/E12000009?format=json&year_start=2017&year_end=2017" -o businesses_250_SW_WMid.json
				
Content of file businesses_250_SW_WMid.json:

[
    {
        "year":2017,
        "region":"E12000005",
        "sizeband":"emps_250_plus",
        "value":600
    },
    {
        "year":2017,
        "region":"E12000009",
        "sizeband":"emps_250_plus",
        "value":500
    }
]