Thank you for purchasing an Emapsite Query-API product. Our Query-API products provide a
restful-API web service interface to query datasets managed/maintained by Emapsite,
leaving you free to run your business.
Emapsite Query-API products are intended to be integrated into a software application
which provides easy-to-understand query parameter entry and display of returned
attributes.
The information provided here will help you get the most from the product you’ve
purchased. Everything you need to get started and interact successfully with the service
is here. And our Customer Support team is on hand to help you, as required.
The API endpoint is encrypted with HTTPS protocol and protected behind a BASIC authentication
process requiring the inclusion of a username and a passkey in the header of every request.
The following JavaScript illustrates how to add a BASIC authentication header to your
requests.
1 var user = 'Your API Key';
2 var pass = 'Your Pass Phrase'
3
4 headers.set('Authorization', 'Basic ' + base64.encode(user + ":" + pass));
Query API Products
Each of our Query-API products is described below. Additional product information is
available from products@emapsite.com
Addressible
Introduction
This Query-API product provides address information for up to 30 million geocoded Royal Mail
delivery point addresses in GB (England, Scotland, Wales).
Summary of API Functionality
The Addressible dataset can be queried by one of five different methods:
Postcode
Postcode and building number
Postcode and building name
UDPRN (the Royal Mail Unique Delivery Point Reference Number)
UPRN (the Ordnance Survey Unique Property Reference Number)
The relevant query input parameter(s) should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the
input values.
API Request Examples
The following five methods for querying the API are available:
Query by Postcode
This scenario allows for a single postcode value (with or without a space character)
to be submitted, with the results listing up to 100 addresses matching this value:
This scenario allows for a single postcode value and a single building number to be
submitted, with the result listing attributes for the single address matching these
values:
This scenario allows for a single postcode value and a single building name to be
submitted, with the result listing attributes for the single address matching these
values:
Upon submission of a valid request, the API service will return an XML file
containing one or more property records. For each property record available, a
static series of attribute values are returned from the Addressible dataset, as
follows
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
The AddressPollution Query queries the AddressPollution dataset to provide air pollution
data for over 30 million addresses within GB. The product returns address information,
concentrations of Nitrogen Dioxide and Particulate Matter (2.5 and 10 microns) and a
pollution ‘rank’ and ‘percentile’ for each property.
Functionality
The AddressPollution dataset can be queried by one of five different methods:
Postcode
Postcode and building number
Postcode and building name
UDPRN (the Royal Mail Unique Delivery Point Reference Number)
UPRN (the Ordnance Survey address reference)
The relevant query input parameter(s) should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the
input values.
API Request Examples
The following five methods for querying the API are available:
Query by Postcode
This scenario allows for a single postcode value (with or without a space character)
to be submitted, with the results listing up to 100 addresses matching this value:
This scenario allows for a single postcode value and a single building number to be
submitted, with the result listing attributes for the single address matching these
values:
This scenario allows for a single postcode value and a single building name to be
submitted, with the result listing attributes for the single address matching these
values:
Upon submission of a valid request, the API service will return an XML file
containing one or more property records. For each property record available, a
static series of attribute values are returned from the AddressPollution dataset, as
follows
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
This Query-API product returns an indication of the likelihood of natural ground movement at postcode level in GB.
It queries the New GeoSure Insurance Product from British Geological Survey. The dataset does not cover man-made
hazards and is typically for pre-screening of a ground risk hazard ahead of a site inspection
Functionality
The BGS NewGIP dataset can be queried by postcode
The relevant query input parameter(s) should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the
input values.
Upon submission of a valid request, the API service will return an XML file containing the likelihood of ground
movement in that postcode displayed as a “class”, along with the postcode and the version of BGS NewGIP queried (NB.
Important for Insurance sector clients), as follows
This Query-API enables customers to query the Emapsite Landpack Polygons dataset containing
HM Land Registry (HMLR) index polygons for England & Wales supplemented with title ownership
and energy performance information.
Functionality
The API allows for querying of the Emapsite Landpack Polygons dataset by one of four
methods, listed below:
Postcode
Postcode with building number
Postcode with building name
UPRN
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
API Request Example
The following four methods for querying the API are available:
Query by Postcode
This scenario allows for a single postcode value (with or without a space character)
to be submitted, with the results listing all properties matching this value:
This scenario allows for a single postcode value and a single building number to be submitted, with the result
listing attributes for the property matching these values:
This scenario allows for a single postcode value and a single building name to be submitted, with the result listing
attributes for the property matching these values:
Upon submission of a valid request, the API service will return an XML file
containing one or more property records. For each property record available, a
static series of attribute values are returned from the Emapsite Landpack Polygons dataset,
as follows:
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
The Emapsite Subsitree GB Query-API provides an initial screening mechanism for people concerned about threats posed to
property by the presence of environmental hazards, such as trees and subsidence-prone soils (e.g. clay).
Functionality
The dataset is queried using a UPRN and returns a fixed set of attributes, plus a warning to refer a property for
further investigation (perhaps a site inspection) where trees are within a certain distance of the property. The UPRN is
either known or could be found by using the Addressible Query-API (querying by postcode+building number) – see above.
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
Upon submission of a valid request, the API service will return an XML file containing an indication of the threats
posed to property by the presence of environmental hazards.
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
This XML Query-API product provides a postcode and property-level indication of the likelihood of flooding. It is based
on Ambiental FloodScore Climate dataset and considers the combined effects of all flood sources (fluvial, pluvial and
tidal) for the present day.
Functionality
FloodNow Query-API can be queried by one of four methods:
Postcode
Postcode and building number
Postcode and building name
UPRN (the OrdnanceSurvey Unique Property Reference Number)
The relevant query input parameter(s) should be appended to the end of the query URL with the following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
API Request Examples
Query by Postcode
This scenario allows for a single postcode value (with or without a space character) to be submitted, with
the
results listing up to 100 addresses matching this value:
This scenario allows for a single postcode value and a single building number to be submitted, with the
result
listing attributes for the single address matching these values:
This scenario allows for a single postcode value and a single building name to be submitted, with the result
listing
attributes for the single address matching these values:
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
This XML Query-API product provides a postcode and property-level prediction of the likelihood of flooding in the
future. It is based on Ambiental FloodScore Climate dataset which uses UKCP18 climate prediction data. The product
considers the combined effects of all flood sources (fluvial, pluvial and tidal) in a Medium Emissions scenario based on
Representation Concentration Pathway 6.0 (RCP6.0).
Functionality
Flood Outlook Query-API can be queried by one of four methods:
Postcode
Postcode and building number
Postcode and building name
UPRN (the Ordnance Survey Unique Property Reference Number)
The relevant query input parameter(s) should be appended to the end of the query URL with the following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
API Request Examples
Query by Postcode
This scenario allows for a single postcode value (with or without a space character) to be submitted, with
the
results listing up to 100 addresses matching this value:
This scenario allows for a single postcode value and a single building number to be submitted, with the
result
listing attributes for the single address matching these values:
This scenario allows for a single postcode value and a single building name to be submitted, with the result
listing
attributes for the single address matching these values:
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
This is Query-API product returns HM Land registry property ownership information, including property boundary geometry
definition (HMLR ‘index’ polygon) for those properties intersecting with the query geometry.
NOTE: This product is scheduled to be withdrawn
Functionality
The dataset is queried using the geospatial geometry of an area-of-interest (AoI) polygon defined by Well Known
Text(WKT).
The maximum number of results to be returned and the number of results to be displayed per page can be specified, to
reduce the query time and improve readability.
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
This is Query-API product returns HM Land registry property ownership information, including a property boundary
geometry definition (HMLR ‘index’ polygon).
Functionality
The dataset is queried by Title Number (whereas the Emapsite LandPack Polygon Query-API product can be queried by
postcode, postcode with building number, postcode with building name and/or UPRN).
The maximum number of results to be returned and the number of results to be displayed per page can be specified.
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
<query_results>
<query>
<name>HMLR lookup by title</name>
</query>
</query_results>
JBA Floodability GB Score with Refer - Query by UPRN
Introduction
This Query-API product requires entry of a UPRN to provide an indication of the likelihood of flooding at a
property. Property UPRN can be identified using the Addressible Query-API product – see above.
Functionality
The query returns a composite 'floodability' rating score (0=Low to 5=very high) for two flood scenarios (defended
and undefended). Rating scores are defined using flood depths for a combination of flood types in a range of flood
'return' periods between 1-in-20 years and 1-in-1,000 years (where more severe events happen less often)
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
This Query-API product requires entry of a UPRN to provide an indication of the likelihood of flooding at a
property. Property UPRN can be identified using the Addressible Query-API product – see above.
Functionality
The query returns a composite 'floodability' rating indicated as a colour written in text (Green = very low to Black2
= very high). Rating scores are defined using flood depths for a combination of flood types in a range of flood
'return' periods between 1-in-20 years and 1-in-1,000 years (where more severe events happen less often)
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
This Query-API product requires entry of a postcode to provide an indication of the likelihood of flooding at a property in Northern Ireland.
Functionality
The dataset is queried using a postcode and returns a composite 'floodability' rating score (0=Low to 5=very high) which
indicates the likelihood of flooding in that postcode area. Rating scores are defined using flood depths for a
combination of flood types in a range of flood 'return' periods between 1-in-20 years and 1-in-1,000 years (where more
severe events happen less often).
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML file containing one record for every address matching the input values.
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters –
postcode contains a typo or building number does not exist), the service returns the
following empty XML response:
The SearchAddress Query API provides address information by querying the Ordnance Survey AddressBase-Plus dataset (containing over 37 million addresses within GB).
Functionality
The dataset can be queried by seven different methods:
Organisation Name
Building (name or number)
Street
Town
Postcode
Output
Country (England, Scotland or Wales)
Any combination of these six input parameters can be used together in a single search to refine results further. The ‘full’ URL containing all possible input parameters is:
https://api.emapsite.com/dataservice.svc/api/Search?orgName=&building=&street=&town=&postcode=&output=
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML or Json file containing one record for every address matching the input values. Unless specified in the query, the default output is an XML file.
API Request Examples
Query by Organisation Name
Allows for a single Organisation Name value to be submitted.
This (optional) parameter can be used to define whether the response data is provided in XML or Json format (Note: if this parameter is not provided, the default output is XML).
Upon submission of a valid request, the API service will return an XML or Json file (default = XML) containing address
information for all records matching the input parameter. The example below has been truncated to show a single record.
Where no records are found in the dataset matching the query values or when an
invalid query is submitted (e.g. not matching the allowed input parameters, the service returns the following empty XML response:
The SearchPlace Query API product queries the Place Names component of the OS OpenNames dataset.
Functionality
The dataset can be queried by entering a text string for a place name and country.
Place
Country (England, Scotland or Wales)
Output
The relevant query input parameters should be appended to the end of the query URL with the
following syntax:
¶meter_name=value
Results are provided as an XML or JSON file containing one record for every potential ‘place’ matching the input
values. A ‘similarity’ attribute provides a matching score (based on similar spelling and pronunciation), with the
results being sorted in descending score order.
Unless specified in the query, the default output is an XML file.
API Request Examples
Query by Place
This (mandatory) parameter allows for a single Place Name value to be submitted.
Upon submission of a valid request, the API service will return an XML or JSON file (default is XML) containing records
with coordinate information for the place name entered, presented descending order of the ‘similarity’ score (1 to 0).
The example below has been truncated to show a single record.
Where no records are found in the dataset matching the query values or when an invalid query is submitted, the service returns the following empty response:
We have tried to cover all the bases, but there might still be a few questions. If your issue is not listed below, please contact our Customer Support team
I've received my email, but
I can't find my API Key or Password.
You should have received your API Key and password in your welcome email.
My API Key and/or Password
doesn't work.
Please ensure you've copied the API Key and Password from email correctly.
I'm having trouble
integrating with my GIS application software
The step by step is contained in the integrations section, but we'd be delighted to
help you.
I'm using the service but
I'm receiving an error message.
Please check that you have entered an allowable query input parameter and/or that the parameter has been entered correctly.
You may have received one of the following errors:
API Key Source has expired. - Please contact our Customer Support team to renew your subscription.
API Key Source has been suspended. - it is possible that the API-key was suspended because the
purchased tariff has been exceeded. Our customer support team will be pleased to help you upgrade your subscription.
API Key Source has been suspended. - it is possible that the API-key was suspended because the
purchased tariff has been exceeded. Our customer support team will be pleased to help you upgrade your subscription.
Known Limitations
We are not aware of any limitations in using these products. If you encounter something unexpected, please report to products@emapsite.com
