Jersey Address API
The viaEuropa Jersey Address API provides programmatic search of Jersey address records using various search criteria. Typical usage would be to obtain an address using a Unique Property Reference Number (UPRN) or get all addresses that use a particular postcode. Geographical searches are also possible to identify, for example, the nearest address to a location coordinate.
API Request Format
End Point
The base end point for the Jersey Address API is:
viaEuropa ID
All requests must include the 20-character API ID provided by Europa Technologies as part of the URI.
This will always be in the format of four blocks of five uppercase alpha-numeric characters, each block separated by a dash:
In all the following example requests you should substitute {id} with your own ID.
All requests are submitted to the following end-point:
Results are returned as JSON (default), GeoJSON or XML. See API Response Format below for full details.
Making Queries
All queries are run against the address gazetteer of the Jersey Basemap product as indicated by the /jersey/jbm/ path of the address end-point. A number of methods are provided to query an address. Select one of the parameters below to make a request.
By UPRN
Querying the API by UPRN, if known, is the simplest way to return an address. The request can be submitted in the following format:
where:
{id} is your viaEuropa ID
{uprn} is a valid Unique Property Reference Number (UPRN)
By Postcode
Query the API by Postcode to return all the addresses that fall within that postcode sorted by name and number :
where:
{id} is your viaEuropa ID
{postcode} is a correctly formatted British postcode.
By Address Text
Querying the API by free text is possible using the following request format. This can be useful for incomplete or badly formed input.
where:
{id} is your viaEuropa ID
{queryString} is a free text address
The API will return the best match or matches for the free text provided. The more fields that can be provided in the free text the higher the likelihood of a good match. Matching against poorly formed, or partial addresses is possible, but results are not guaranteed and false matches are always possible. The supplied address text should be in standard address format and inclued a postcode or partial postcode at the end of the string if possible.
Responses to address match queries always include a result parameter called matchscore. This indicates the character by character similarity of the match between the query term and the full address of the response. A perfect match is 100. Results are ordered by matchscore in descending order to return the best matches first. If a single match is returned then a higher confidence can be given to the returned address. Partial or ambiguous addresses can be submitted, but will return multiple results. For example q=Portelet+Drive will return all the addresses that contain Portelet Drive anywhere in the address. This may be useful in some scenarios.
By Geometry
Geographic searches for addresses can be executed by passing point coordinates.
Point
Searching based on proximity to a Longitude+Latitude coordinate is possible using the point parameter:
This type of request can be used to identify addresses that are close to a coordinate obtained from systems such as GPS. They are sometime referred to as a 'reverse geocode'.
where:
{id} is your viaEuropa ID
{lon} is a valid decimal Longitude coordinate.
{lat} is a valid decimal Latitude coordinate.
Note Coordinates are presented as longitude/latitude and not conventional order. If no radius parameter is provided then results are limited to a search radius of 1000 metres. The maximum radius permitted is 1000m.
Results can also be limited to the nearest n addresses by addition of the maxresults parameter. See below.
Modifiers
The results from any query can be modified by the addition of one or several of the modifiers below.
Field Sets
Jersey Addresses contains 30 fields of information. To make the response more manageable fields have been grouped into subsets which can be invoked using the fieldset parameter:
| fieldset | response |
|---|---|
| summary | UPRN, address, matchscore fields. Default |
| postal | Returns all postal address fields as separate fields |
| all | Returns all fields provided in Jersey Address |
Other Modifiers
There are other modifiers that can be added to requests in order to alter the content or format of the response.
| Field | Description | Type |
|---|---|---|
| maxresults | Add a limit to the number of results returned. Default = 1000 | Integer |
| jobid | A user code passed in the request that is returned in the metadata | AlphaNumeric |
| format | The response format. json(default), geojson or xml. | AlphaNumeric |
API Response
Format
All responses to requests to the viaEuropa Jersey Address API are returned in JSON (default), GeoJSON or XML format. The coordinates are returned in EPSG:4326 (WGS84) when the format is GeoJSON.
Structure
There are two root elements in the response:
- results contains the results of the query
- metadata contains information about the request
Results
The results element contains the results of the query in an array called Address
JSON
"results": [
{
"address": [
{
"uprn": 69404018,
"fulladdress": "Government of Jersey, 19-21 Broad Street, St. Helier, JE2 3RR",
"matchscore": 100
}
]
}
XML
<results>
<address>
<uprn>10033332750</uprn>
<fulladdress>Government of Jersey, 19-21 Broad Street, St. Helier, JE2 3RR</fulladdress>
<matchscore>100</matchscore>
</address>
</results>
GeoJSON
{
"type": "FeatureCollection",
"name": "jbm",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": [
{
"type": "Feature",
"id": 69404018,
"geometry": {
"type": "Point",
"coordinates": [
-2.10819672,
49.18428866
]
},
"properties": {
"uprn": 69404018,
"matchscore": 100,
"fulladdress": "Government of Jersey, 19-21 Broad Street, St. Helier, JE2 3RR"
}
}
]
}
Note The above response contains the default field set that is returned to any request. Other fields may be added according to the fieldset parameter as described earlier.
Metadata
The metadata element contains information about the request and results returned: JSON
"metadata": {
"querytime": 0.04819,
"vintage" “2024q1”,
"jobid": null,
"count": 1,
"maxResults": 1000,
"status": "OK"
}
<metadata>
<querytime>0.04819</querytime>
<vintage>1</vintage >
<jobid/>
<count>1</count>
<maxResults>1000</maxResults>
<status>OK</status>
</metadata>
| Element | Description |
|---|---|
| querytime | The time in seconds taken to run the database query |
| vintage | Text string date of release of the data in use |
| count | Number of results returned |
| maxResults | Maximum number of results returned |
| status | Status of the response, should be 'OK' |