Emapsite.com

Introduction To Query API

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.

Customer Support Telephone: 01189 973 6883
Customer Support Email: customersupport@emapsite.com
Emapsite Address The Hub
Fowler Avenue
Farnborough
GU14 7JF
United Kingdom
Emapsite Website: www.emapsite.com

Getting Started

To use Emapsite's Query-API products you need the following:

  • Your API Key URL
  • Your API Key Username
  • Your API Key Passphrase

These can be found in your welcome email.

You can also find all your licensed products by entering your API Key name and Passphrase at:

Authentication

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:

&parameter_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:

  1. 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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&postcode=

    Example: Postcode = B74 4PZ

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&postcode=B744PZ

  2. Query by Postcode and Building Number

    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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&postcode= &building_number=

    Example: Postcode=B744PZ and Building Number=37

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&postcode= B744PZ&building_number=37

  3. Query by Postcode and Building Name

    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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible &postcode=&building_name=

  4. Query by UDPRN

    This scenario allows for a single UDPRN number to be submitted, with the result listing the single address matching this value:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&udprn=

    Example: UDPRN=945751

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&udprn=945751

  5. Query by UPRN

    This scenario allows for a single UPRN number to be submitted, with the result listing the single address matching this value:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&uprn=

    Example: UPRN=100070603776

    https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&uprn=100070603776

API Response Summary

  • Valid query

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

        <query_results>
            <query>
                <name>=Addressible</name>
                <row>
                    <column name="organisation_name"/>
                    <column name="sub_building_name"/>
                    <column name="building_number">37</column>
                    <column name="building_name"/>
                    <column name="thoroughfare_and_descriptor">Streetly Crescent</column>
                    <column name="double_dependent_locality"/>
                    <column name="dependent_locality"/>
                    <column name="posttown">SUTTON COLDFIELD</column>
                    <column name="postcode">B74 4PZ</column>
                    <column name="udprn">945751</column>
                    <column name="uprn">100070603776</column>
                    <column name="class">R</column>
                    <column name="easting">409796</column>
                    <column name="northing">299280</column>
                    <column name="longitude">-1.8568238</column>
                    <column name="latitude">52.5912494</column>
                </row>
            </query>
        </query_results>
  • Invalid Query (or No Results Found)

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:

Example: 234smithstreet entered as a Postcode

https://api.emapsite.com/dataservice.svc/api/Query?Source=Addressible&postcode=234smithstreet 

        <query_results>
            <query>
                <name>Addressible</name>
            </query>
        </query_results>

Address Pollution

Introduction

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:

&parameter_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:

  1. 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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&postcode=

    Example: Postcode = B74 4PZ

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&postcode=B744PZ

  2. Query by Postcode and Building Number

    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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&postcode=&building_number=

    Example: Postcode=B744PZ and Building Number=37

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&postcode=B744PZ&building_number=37

  3. Query by Postcode and Building Name

    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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&postcode=&building_name=

  4. Query by UDPRN

    This scenario allows for a single UDPRN number to be submitted, with the result listing the single address matching this value:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&udprn=

    Example: UDPRN=945751

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&udprn=945751

  5. Query by UPRN

    This scenario allows for a single UPRN number to be submitted, with the result listing the single address matching this value:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&uprn=

    Example: UPRN=100070603776

    https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&uprn=100070603776

API Response Summary

  • Valid query

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

        <query_results>
            <query>
                <name>AddressPollution</name>
                <row>
                    <column name="organisation_name"/>
                    <column name="sub_building_name"/>
                    <column name="building_number">37</column>
                    <column name="building_name"/>
                    <column name="thoroughfare_and_descriptor">Streetly Crescent</column>
                    <column name="double_dependent_locality"/>
                    <column name="dependent_locality"/>
                    <column name="posttown">SUTTON COLDFIELD</column>
                    <column name="postcode">B74 4PZ</column>
                    <column name="udprn">945751</column>
                    <column name="uprn">100070603776</column>
                    <column name="class">R</column>
                    <column name="easting">409796</column>
                    <column name="northing">299280</column>
                    <column name="longitude">-1.8568238</column>
                    <column name="latitude">52.5912494</column>
                    <column name="no2conc">17.682727814</column>
                    <column name="pm10conc">16.17682457</column>
                    <column name="pm2_5conc">10.232028961</column>
                    <column name="rank">3</column>
                    <column name="percentile">51</column>
                </row>
            </query>
        </query_results>
  • Invalid Query (or No Results Found)

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:

Example: 234smithstreet entered as a Postcode

https://api.emapsite.com/dataservice.svc/api/Query?Source=addresspollution&postcode=234smithstreet 

        <query_results>
            <query>
                <name>AddressPollution</name>
            </query>
        </query_results>

BGS NewGIP Lite

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

 

API Request Example

  • Query by Postcode


    https://api.emapsite.com/dataservice.svc/api/Query?Source=newgip_lite&postcode=

    Example: Postcode = B74 4PZ

    https://api.emapsite.com/dataservice.svc/api/Query?Source=newgip_lite&postcode=B744PZ

API Response Summary

  • Valid query

    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

<query_results>
    <query>
        <name>BGSNewGIPLite</name>
        <row>
            <column name="postcode">B74 4PZ</column>
            <column name="class">Low</column>
            <column name="version">newGIP_v8_2021.3</column>
        </row>
    </query>
</query_results>
  • Invalid Query (or No Results Found)
<query_results>
    <query>
        <name>BGS NewGIP Lite</name>
    </query>
</query_results>

Emapsite Landpack Polygons

Introduction

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:

&parameter_name=value

 

API Request Example

The following four methods for querying the API are available:

  1. 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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&postcode=

    Example: Postcode = B74 4PZ

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&postcode=B744PZ

  2. Query by Postcode and Building Number

    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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&postcode=&building_number=

    Example: Postcode=B744PZ and Building Number=37

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&postcode=B744PZ&building_number=37

  3. Query by Postcode and Building Name

    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:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&postcode=&building_name=

  4. Query by UPRN

    This scenario allows for a single UPRN number to be submitted, with the result listing the single property matching this value:

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&uprn=

    Example: Example: UPRN=100070603776

    https://api.emapsite.com/dataservice.svc/api/Query?Source=landpack_polygons&uprn=100070603776

API Response Example

  • Valid query

    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:

<query_results>
    <query>
        <name> Landpack_Polygons</name>
            <row>
                <column name="uprn">100070603776</column>
                <column name="postcode">B74 4PZ</column>
                <column name="building_number">37</column>
                <column name="building_name"/>
                <column name="sub_building_name"/>
                <column name="polygon_id">24290573</column>
                <column name="title_no">WM126586</column>
                <column name="insert_date">2002-09-20T00:00:00</column>
                <column name="update_date">2002-09-20T00:00:00</column>
                <column name="rec_status">A</column>
                <column name="estate_interest">Estate in land</column>
                <column name="class_of_title">Absolute freehold title</column>
                <column name="registered_status">Registered</column>
                <column name="property_type">House</column>
                <column name="built_form">Detached</column>
                <column name="construction_age_band">England and Wales: 1976-1982</column>
                <column name="current_energy_rating">C</column>
                <column name="environment_impact_current">67</column>
                <column name="energy_consumption_current">156</column>
                <column name="current_energy_efficiency">71</column>
                <column name="co2_emissions_current">5.4</column>
                <column name="co2_emiss_curr_per_floor_area">30</column>
                <column name="wkt">MULTIPOLYGON(((409752.45 299300.7,409752.85 299301.4,409758.3 299310.35,409758.8 299311.2,409778.25 299297.3,409800.65 299281.1,409812.08 299272.83,409804.809 299262.842,409789.2 299274.3,409774.6 299284.75,409752.45 299300.7)))</column>
            </row>
    <query>
<query_results>
  • Invalid Query (or No Results Found)

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:

Example: 234 smith street entered as a Postcode

<query_results>
    <query>
        <name>HMLR_EPC_Query</name>
    </query>
</query_results>

Emapsite Subsitree

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Example

  • Query by UPRN

    https://api.emapsite.com/dataservice.svc/api/Query?Source=subsitree_gb_uprn&uprn=

    Example: UPRN=100070603776

    https://api.emapsite.com/dataservice.svc/api/Query?Source=subsitree_gb_uprn&uprn=100070603776

API Response Summary

  • Valid query

    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.

<query_results>
    <query>
        <name>subsitree_gb_uprn</name>
        <row>
            <column name="uprn">100070603776</column>
            <column name="environmental">1</column>
            <column name="clay">2</column>
            <column name="sand">2</column>
            <column name="silt">0</column>
            <column name="soft">0</column>
            <column name="peat">0</column>
            <column name="composite_total">5</column>
            <column name="weighted_score">55</column>
            <column name="refer">true</column>
        </row>
    </query>
<query_results>
  • Invalid Query (or No Results Found)

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>subsitree_gb_uprn</name>
    </query>
</query_results>

FloodNow Query-API

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Examples

  1. 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:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&postcode=

    Example: Postcode = FY78RL

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&postcode=FY78RL

  2. Query by Postcode and Building Number

    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:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&postcode=

    Example: Postcode=FY78RL and Building Number=21

    [An address approximately 0.5 miles from the seafront at Fleetwood, Lancashire]

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&postcode=FY78RL&building_number=21

  3. Query by Postcode and Building Name

    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:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&postcode=<postcode>&building_number=<building_name>

  4. Query by UPRN

    This scenario allows for a single UPRN number to be submitted, with the result listing the single address matching this value:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&uprn=

    Example: UPRN=100010702779

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_presentday&uprn=100010702779

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing attributes for one or more property records, as follows

<query_results>
<query>
    <name>FloodNowQuery</name>
    <row>
        <column name="uprn">100010702779</column>
        <column name="x_coor">331970</column>
        <column name="y_coor">445381</column>
        <column name="undef_f_rr">0</column>
        <column name="undef_p_rr">0</column>
        <column name="undef_t_rr">73</column>
        <column name="undef_c_score">4</column>
        <column name="undef_c_rr">73</column>
        <column name="undef_c_adr">0.19172</column>
        <column name="undef_c_aal">441</column>
        <column name="def_bin">0</column>
    </row>
</query>
</query_results>
  • Invalid Query (or No Results Found)

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:

Example: Postcode entered = NNXXNN

<query_results>
    <query>
        <name> FloodNowQuery </name>
    </query>
</query_results>

Flood Outlook Query-API

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Examples

  1. 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:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&postcode=

    Example: Postcode = FY78RL

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&postcode=FY78RL

  2. Query by Postcode and Building Number

    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:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&postcode=

    Example: Postcode=FY78RL and Building Number=21

    [An address approximately 0.5 miles from the seafront at Fleetwood, Lancashire]

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&postcode=

  3. Query by Postcode and Building Name

    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:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&postcode=<postcode>&building_number=<building_name>

  4. Query by UPRN

    This scenario allows for a single UPRN number to be submitted, with the result listing the single address matching this value:

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&uprn=

    Example: UPRN=100010702779

    https://api.emapsite.com/dataservice/api/Query?Source=ambiental_climate_floodscoreclimate_medem&uprn=100010702779

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing attributes for one or more property records, as follows

<query_results>
    <query>
        <name>FloodOutlookQuery</name>
        <row>
            <column name="uprn">100010702779</column>
            <column name="postcode">FY7 8RL</column>
            <column name="building_number">21</column>
            <column name="building_name"/>
            <column name="x_coor">331970</column>
            <column name="y_coor">445381</column>
            <column name="undef_c_score_2027">4</column>
            <column name="undef_c_rr_2027">74</column>
            <column name="undef_c_adr_2027">0.19225</column>
            <column name="undef_c_aal_2027">442</column>
            <column name="undef_c_score_2055">4</column>
            <column name="undef_c_rr_2055">76</column>
            <column name="undef_c_adr_2055">0.19757</column>
            <column name="undef_c_aal_2055">454</column>
            <column name="undef_c_score_2093">4</column>
            <column name="undef_c_rr_2093">78</column>
            <column name="undef_c_adr_2093">0.20315</column>
            <column name="undef_c_aal_2093">467</column>
        </row>
    </query>
</query_results>
  • Invalid Query (or No Results Found)

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:

Example: Postcode entered = NNXXNN

<query_results>
    <query>
        <name> FloodOutlookQuery </name>
    </query>
</query_results>

HMLR Polygons - Query by Geometry

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Example

  • Query by Geometry (WKT definition)

    https://api.emapsite.com/dataservice.svc/api/Query?Source=hmlrtitletenuregeom&polygon=POLYGON

    Example: ((300000 300000, 300000 300200, 300200 300200, 300200 300000, 300000 300000))

    https://api.emapsite.com/dataservice.svc/api/Query?Source=hmlrtitletenuregeom&polygon=POLYGON((300000 300000, 300000 300200, 300200 300200, 300200 300000, 300000 300000))

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing ownership information for the property Title Number entered.

<query_results>
    <query>
        <name>HMLR title tenure lookup by geom</name>
        <row>
            <column name="title_no">CYM31975</column>
            <column name="rec_status">A</column>
            <column name="insert_date">2001-08-19T00:00:00</column>
            <column name="update_date">2001-08-19T00:00:00</column>
            <column name="wkt">MULTIPOLYGON(((299743 299585,299743 299598.5,299738.238 299622.223,299716.5 299730.5,299716 299733.5,299712.5 299773.5,
            299704.44 299848.96,299700.55 299885.35,299771.53 299893.8,299942.5 299914,299977 299918,300000 299931.5,300048 299962.5,300102.9 300000,300105.76 300002.2,300106.75 300000,300112.03 299988.22,300135.08 299936.76,300138.4 299929.34,300139 299928,300187.5 299819.5,300239.5 299706.5,300246.193 299691.442,300287.5 299598.5,300325.69 299515.07,300295.52 299500,300279.5 299492,300191.5 299446.5,300073 299386.5,300000 299350.25,299984.26 299343.61,299876 299442.5,299875 299448.5,299822.71 299500,299744.38 299577.15,299742.5 299579,299743 299585)))</column>
        </row>
    </query>
</query_results>
  • No Results Found

Where no records are found in the dataset matching the query values, the service returns the following empty XML response:

<query_results>
    <query>
        <name>HMLR title tenure lookup by geom</name>
    </query>
</query_results>

Invalid Query (or No Results Found)

When an invalid query is submitted (e.g. an incorrect WKT definition or no WKT definition), a request error may be displayed.

Example: No WKT definition included

https://api.emapsite.com/dataservice.svc/api/Query?Source=hmlrtitletenuregeom&polygon=POLYGON

request error example

HMLR Polygons - Query by Title Number

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Example

  • Query by HM Land Registry Title Number

    https://api.emapsite.com/dataservice.svc/api/Query?Source=hmlrlookupbytitle&title_no=

    Example: WM126586

    https://api.emapsite.com/dataservice.svc/api/Query?Source=hmlrlookupbytitle&title_no= WM126586

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing ownership information for the property Title Number entered.

<query_results>
    <query>
        <name>HMLR lookup by title</name>
        <row>
            <column name="title_no">WM126586</column>
            <column name="rec_status">A</column>
            <column name="insert_date">2002-09-20T00:00:00</column>
            <column name="update_date">2002-09-20T00:00:00</column>
            <column name="polygon_id">24290573</column>
            <column name="st_astext">MULTIPOLYGON(((409752.45 299300.7,409752.85 299301.4,409758.3 299310.35,409758.8 299311.2,409778.25 299297.3,
            409800.65 299281.1,409812.08 299272.83,409804.809 299262.842,409789.2 299274.3,409774.6 299284.75,409752.45 299300.7)))</column>
        </row>
    </query>
</query_results>

Invalid Query (or No Results Found)

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Example

  • Query by URPN

    &parameter_name=value

    Example: UPRN=100070603776

    https://api.emapsite.com/dataservice.svc/api/Query?Source=jba_flood_score_gb_uprn&uprn=100070603776

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing floodability information for the property UPRN entered.

<query_results>
    <query>
        <name>jba_flood_score_gb_uprn</name>
        <row>
            <column name="undefended">2</column>
            <column name="defended">2</column>
            <column name="refer">false</column>
        </row>
    </query>
</query_results>
  • Invalid Query (or No Results Found)

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>jba_flood_text_gb_uprn</name>
    </query>
</query_results>

JBA Floodability GB Text - 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 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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Example

  • Query by URPN

    https://api.emapsite.com/dataservice.svc/api/Query?Source=jba_flood_text_gb_uprn&uprn=

    Example: UPRN=100070603776

    https://api.emapsite.com/dataservice.svc/api/Query?Source=jba_flood_text_gb_uprn&uprn=100070603776

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing floodability information for the property UPRN entered.

<query_results>
    <query>
        <name>jba_flood_text_gb_uprn</name>
        <row>
            <column name="undefended">Green</column>
            <column name="defended">Green</column>
        </row>
    </query>
</query_results>
  • Invalid Query (or No Results Found)

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>jba_flood_text_gb_uprn</name>
    </query>
</query_results>

JBA Floodability NI Score – Query by Postcode

Introduction

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:

&parameter_name=value

Results are provided as an XML file containing one record for every address matching the input values.

API Request Example

  • Query by Postcode

    https://api.emapsite.com/dataservice.svc/api/Query?Source=jba_flood_score_ni_postcode&postcode=

    Example: Postcode=BT39JH

    https://api.emapsite.com/dataservice.svc/api/Query?Source=jba_flood_score_ni_postcode&postcode=BT39J

API Response Summary

  • Valid query

    Upon submission of a valid request, the API service will return an XML file containing floodability information for the property UPRN entered.

<query_results>
    <query>
        <name>jba_flood_score_ni_postcode</name>
        <row>
            <column name=""score"">2</column>
        </row>
    </query>
</query_results>
  • Invalid Query (or No Results Found)

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:

Example: Postcode B74 4PZ (Birmingham postcode)

<query_results>
    <query>
        <name>jba_flood_score_ni_postcode</name>
    </query>
</query_results>

Search Address

Introduction

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:

&parameter_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.

    https://api.emapsite.com/dataservice.svc/api/Search?orgName=

    Example: Organisation Name=

    https://api.emapsite.com/dataservice.svc/api/Search?orgName=

  • Query by building name or number

    Allows for a single building name or number value to be submitted

    https://api.emapsite.com/dataservice.svc/api/Search?building=

    Example: Building Name or number=

    api.emapsite.com/dataservice.svc/api/Search?building=

  • Query by Street Name

    Allows for a single street name value to be submitted

    https://api.emapsite.com/dataservice.svc/api/Search?street=

    Example:  Street Name=

    https://api.emapsite.com/dataservice.svc/api/Search?street=

  • Query by Town Name

    Allows for a single town name value to be submitted

    https://api.emapsite.com/dataservice.svc/api/Search?town=

    Example: Town Name=

    https://api.emapsite.com/dataservice.svc/api/Search?town=

  • Query by Country

    Allows for a single country value to be submitted

    https://api.emapsite.com/dataservice.svc/api/Search?country=

    Example: Country=

    https://api.emapsite.com/dataservice.svc/api/Search?country=

  • Query by Postcode

    Allows for a single postcode value to be submitted (with or without a space character)

    https://api.emapsite.com/dataservice.svc/api/Search?postcode=

    Example: Postcode = B74 4PZ

    https://api.emapsite.com/dataservice.svc/api/Search?postcode=B744PZ

  • Query by Output Format

    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).

    https://api.emapsite.com/dataservice.svc/api/Search?output=

    Example: Output=

    https://api.emapsite.com/dataservice.svc/api/Search?output=

API Response Summary

  • Valid query

    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.

    Example: Postcode = B74 4PZ

<AddressSearch version="1.0" statusCode="SUCCESS">
    <Locations totalResults="27" firstResult="1" resultsPerPage="5000">
        <Location similarity="1">
            <Address type="simple">
                <OrganizationName/>
                <BuildingName/>
                <SubBuildingName/>
                <BuildingNumber>37</BuildingNumber>
                <Street>STREETLY CRESCENT</Street>
                <Town>SUTTON COLDFIELD</Town>
                <AdminArea>BIRMINGHAM</AdminArea>
                <Postcode>B74 4PZ</Postcode>
                <Locality/>
                <ThoroughFare>STREETLY CRESCENT</ThoroughFare>
            </Address>
            <Uprn>100070603776</Uprn>
            <Coordinate crs="EPSG:27700">
                <X>409796</X>
                <Y>299280</Y>
                <Comment>NA</Comment>
            </Coordinate>
        </Location>
  • Invalid Query (or No Results Found)

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:

<AddressSearch version="1.0" statusCode="SUCCESS">
    <Locations totalResults="0"/>
</AddressSearch>

Search Place

Introduction

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:

&parameter_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.

    https://api.emapsite.com/dataservice.svc/api/SearchPlace?place=

    Example: Place=Four Oaks

    https://api.emapsite.com/dataservice.svc/api/SearchPlace?place=Four Oaks

    Example: Place=Four Oaks Country=England

    https://api.emapsite.com/dataservice.svc/api/SearchPlace?place=Four Oaks&country=england

  • Specify Output Format

    This (optional) parameter can be used to define whether the response data is provided in XML or JSON format (Note: Default is XML).

    https://api.emapsite.com/dataservice.svc/api/Search?building=

    Example: Building Name or number=

    https://api.emapsite.com/dataservice.svc/api/SearchPlace?place=&output=

API Response Summary

  • Valid query

    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.

<AddressSearch version="1.0" statusCode="SUCCESS">
    <Locations totalResults="18" firstResult="1" resultsPerPage="5000">
        <Location similarity="1">
            <Place>
                <Name>Four Oaks</Name>
                <County/>
            </Place>
            <Coordinate crs="EPSG:27700">
                <X>424452</X>
                <Y>280504</Y>
                <Comment>NA</Comment>
            </Coordinate>
        </Location>
  • Invalid Query (or No Results Found)

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:

<AddressSearch version="1.0" statusCode="SUCCESS">
    <Locations totalResults="0" firstResult="1" resultsPerPage="5000"/>
</AddressSearch>

FAQs

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

Commonly Asked Questions

You should have received your API Key and password in your welcome email.

Please ensure you've copied the API Key and Password from email correctly.

The step by step is contained in the integrations section, but we'd be delighted to help you.

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