{"_id":"570bcb9900656917001cd553","parentDoc":null,"version":{"_id":"55e06495a44fae0d002146ad","project":"55e06494a44fae0d002146aa","__v":54,"createdAt":"2015-08-28T13:39:33.907Z","releaseDate":"2015-08-28T13:39:33.907Z","categories":["55e06496a44fae0d002146ae","55e06997a44fae0d002146c2","55e06a6958c5460d0076aa0c","55e06ae66bad670d0081f25c","55e06cc1a44fae0d002146cb","55e06ddda44fae0d002146cd","55e95f261fd7e82300ef359f","55e95fe47fc27b2d00d32cfa","55e96eef358d923700be984d","55e96ef6358d923700be984e","55e96efda7ca823900ad547e","55e96f04a7ca823900ad547f","55e970cc358d923700be9853","55e973f4358d923700be9858","55e973f9a7ca823900ad548c","55e977bf358d923700be985d","55e9780f8b72bb3700b1d5bd","55e97815a7ca823900ad5493","55e9781c358d923700be985f","55e97821461e2a390050f23b","55f963c23bb4bb0d0022d18c","5624c67406e8040d005ed6b2","5624dcf25a86b423009462e8","5625f229d0f87e190014c4ed","5627819fe2ce610d004e3ec8","562781b23a4c6b0d00c4556b","5627837166c62617009d17e2","5627851efcbbc621004ebff1","5627860044c87f0d00fe6491","562e3c6d54a5be0d00070c3e","564c955aae6cb82100dc137a","5652e22abbe7110d00dba748","5652f25523d4262d00b21c58","5652fdad51e4e81900bf2452","5652fdcbb60abb1700bafadc","5654494f65bec717007e0293","565da11a77f0090d005818ff","565f063f413e06170093de18","565f06fb413e06170093de21","56dd6773efaca42900e5f58e","56dd68630c3bb41700b0b037","56dd7d24d5419f170075dfb3","56dd9448c117291700015b60","56dd9454c117291700015b61","577a6f8b9748b80e00ef3f45","577a6f969748b80e00ef3f46","577bba7f6e5f301900fada99","57a9cc8e5b1ace0e00de743f","58aab134c50c33250046b8f8","58aab146aecc3e2500573d4c","58aab1628f862f250076f92e","58aab1938f862f250076f92f","58aab3e5aecc3e2500573d56","58aab3f2aecc3e2500573d57"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":11,"category":{"_id":"55e95fe47fc27b2d00d32cfa","pages":["55ed65182e66b62100994163"],"version":"55e06495a44fae0d002146ad","project":"55e06494a44fae0d002146aa","__v":1,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-04T09:09:56.318Z","from_sync":false,"order":8,"slug":"endpoint","title":"endpoint"},"user":"55eea68fc93e8c17008a109c","editedParams":true,"project":"55e06494a44fae0d002146aa","editedParams2":true,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-11T16:06:49.224Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"javascript","code":"var geoJSON = JSON.stringify({\"type\": \"Feature\", \"geometry\": {\"type\": \"Polygon\",\"coordinates\": [[[437226,115652],[437212,115495],[437387,115495],[437368,115663],[437226,115652]]]},\"properties\": { \"name\": \"OS HQ\"}});\n\nvar req = new XMLHttpRequest();\n\nreq.open(\"POST\", \"https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon?key=[[app:key]]\",true);\n\nreq.setRequestHeader(\"Content-type\", \"application/json\");\n\nreq.onreadystatechange = function () {\n    console.log(req.responseText);\n}\nreq.send(geoJSON);","name":null},{"name":"JQuery","language":"javascript","code":"var geoJSON = JSON.stringify({\"type\": \"Feature\", \"geometry\": {\"type\": \"Polygon\",\"coordinates\": [[[437226,115652],[437212,115495],[437387,115495],[437368,115663],[437226,115652]]]},\"properties\": { \"name\": \"OS HQ\"}});  \n\n$.ajax('https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon?key=[[app:key]]', {\n        data: geoJSON,\n        contentType: \"application/json\",\n        processData: false,\n        crossDomain: true,\n        type: 'POST'\n    }).done(function(data) {\n        console.log(data);\n    });"},{"code":"var querystring = require('querystring');\nvar https = require('https');\n\nvar geoJSON = JSON.stringify({\"type\": \"Feature\", \"geometry\": {\"type\": \"Polygon\",\"coordinates\": [[[437226,115652],[437212,115495],[437387,115495],[437368,115663],[437226,115652]]]},\"properties\": { \"name\": \"OS HQ\"}});\n\nvar post_options = {\n  host: 'api.ordnancesurvey.co.uk',\n\tpath: '/places/v1/addresses/polygon?key=[[app:key]]',\n\tmethod: 'POST',\n\theaders: {\n\t\t'Content-Type': 'application/json',\n\t\t'Content-Length': Buffer.byteLength(geoJSON)\n\t}\n};\n\nvar post_req = https.request(post_options, function(res) {\n    res.setEncoding('utf8');\n    res.on('data', function (d) {\n        process.stdout.write(d);\n    });\n});\n\n  post_req.write(geoJSON);\n  post_req.end();","language":"javascript","name":"Node.js"},{"code":"<?php\n\n\t$geoArray = array (\"type\" => \"Feature\", \"geometry\" => array(\"type\" => \"Polygon\", \"coordinates\" => array([[437226,115652],[437212,115495],[437387,115495],[437368,115663],[437226,115652]])), \"properties\" => array(\"name\"=> \"OS HQ\"));\n\n//Due to the encoding used in json_encode, a pair of square brackets has to be removed from the coordinate array\n\n\t$geoJSON = json_encode($geoArray);\n\t\n    $curl = curl_init();\n\tcurl_setopt($curl, CURLOPT_URL, \"https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon?key=[[app:key]]\");\n\tcurl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Content-Length: '.strlen($geoJSON)));\n\tcurl_setopt($curl, CURLOPT_POST, 1);\n\tcurl_setopt($curl, CURLOPT_POSTFIELDS, $geoJSON);                                                                  \n    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);\n\n    $result = curl_exec ($curl);\n    curl_close ($curl);\n    print \"<pre>$result</pre>\";\n?>","language":"php"},{"code":"<html lang=\"en\" ng-app=\"angularAPI\">\n<head>\n  <meta charset=\"utf-8\">\n  <script src=\"https://ajax.googleapis.com/ajax/libs/angularjs/1.4.9/angular.min.js\"></script>\n</head>\n\n<script type=\"text/javascript\">\n  var osAPI = angular.module('angularAPI', []);\n  \n  var geoJSON = JSON.stringify({\"type\": \"Feature\", \"geometry\": {\"type\": \"Polygon\",\"coordinates\": [[[437226,115652],[437212,115495],[437387,115495],[437368,115663],[437226,115652]]]},\"properties\": { \"name\": \"OS HQ\"}});\n\n  osAPI.controller('apiService', ['$scope', '$http', function($scope, $http) {\n    var key = \"[[app:key]]\";\n    var query = 'https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon?';\n    $http.post(query+'&key='+key, geoJSON).success(function(data) {\n      $scope.output = data.results;\n    });\n  }]);\n</script>\n\n<body ng-controller=\"apiService\">\n  <ul ng-repeat=\"value in output\">\n    <li ng-repeat=\"object in value\">\n      <p>{{object}}</p>\n    </li>\n  </ul>\n</body>\n</html>","language":"javascript","name":"AngularJS"}]},"method":"post","results":{"codes":[{"name":"OK - JSON","status":200,"language":"json","code":"{\n  \"header\" : {\n    \"uri\" : \"https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon\",\n    \"offset\" : 0,\n    \"totalresults\" : 1,\n    \"format\" : \"JSON\",\n    \"dataset\" : \"DPA\",\n    \"lr\" : \"EN,CY\",\n    \"maxresults\" : 100,\n    \"epoch\" : \"38\",\n    \"output_srs\" : \"EPSG:27700\",\n    \"srs\" : \"EPSG:27700\"\n  },\n  \"results\" : [ {\n    \"DPA\" : {\n      \"UPRN\" : \"200010019924\",\n      \"UDPRN\" : \"52126562\",\n      \"ADDRESS\" : \"ORDNANCE SURVEY, 4, ADANAC DRIVE, NURSLING, SOUTHAMPTON, SO16 0AS\",\n      \"ORGANISATION_NAME\" : \"ORDNANCE SURVEY\",\n      \"BUILDING_NUMBER\" : \"4\",\n      \"THOROUGHFARE_NAME\" : \"ADANAC DRIVE\",\n      \"DEPENDENT_LOCALITY\" : \"NURSLING\",\n      \"POST_TOWN\" : \"SOUTHAMPTON\",\n      \"POSTCODE\" : \"SO16 0AS\",\n      \"RPC\" : \"2\",\n      \"X_COORDINATE\" : 437318.0,\n      \"Y_COORDINATE\" : 115539.0,\n      \"STATUS\" : \"APPROVED\",\n      \"LOGICAL_STATUS_CODE\" : \"1\",\n      \"CLASSIFICATION_CODE\" : \"CO01GV\",\n      \"CLASSIFICATION_CODE_DESCRIPTION\" : \"Central Government Service\",\n      \"LOCAL_CUSTODIAN_CODE\" : 1760,\n      \"LOCAL_CUSTODIAN_CODE_DESCRIPTION\" : \"TEST VALLEY\",\n      \"POSTAL_ADDRESS_CODE\" : \"S\",\n      \"POSTAL_ADDRESS_CODE_DESCRIPTION\" : \"A single address\",\n      \"BLPU_STATE_CODE\" : \"2\",\n      \"BLPU_STATE_CODE_DESCRIPTION\" : \"In use\",\n      \"TOPOGRAPHY_LAYER_TOID\" : \"osgb1000002682081995\",\n      \"LAST_UPDATE_DATE\" : \"01/09/2010\",\n      \"ENTRY_DATE\" : \"01/09/2010\",\n      \"BLPU_STATE_DATE\" : \"01/09/2010\",\n      \"LANGUAGE\" : \"EN\",\n      \"MATCH\" : 1.0,\n      \"MATCH_DESCRIPTION\" : \"EXACT\"\n    }\n  } ]\n}"},{"status":200,"language":"xml","code":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<AddressAPI>\n    <header>\n        <uri>https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon?format=xml</uri>\n        <query>format=xml</query>\n        <offset>0</offset>\n        <totalresults>1</totalresults>\n        <format>xml</format>\n        <dataset>DPA</dataset>\n        <lr>EN,CY</lr>\n        <maxresults>100</maxresults>\n        <epoch>38</epoch>\n        <output_srs>EPSG:27700</output_srs>\n        <srs>EPSG:27700</srs>\n    \n    </header>\n    <results>\n        <DPA>\n            <UPRN>200010019924</UPRN>\n            <UDPRN>52126562</UDPRN>\n            <ADDRESS>ORDNANCE SURVEY, 4, ADANAC DRIVE, NURSLING, SOUTHAMPTON, SO16 0AS</ADDRESS>\n            <ORGANISATION_NAME>ORDNANCE SURVEY</ORGANISATION_NAME>\n            <BUILDING_NUMBER>4</BUILDING_NUMBER>\n            <THOROUGHFARE_NAME>ADANAC DRIVE</THOROUGHFARE_NAME>\n            <DEPENDENT_LOCALITY>NURSLING</DEPENDENT_LOCALITY>\n            <POST_TOWN>SOUTHAMPTON</POST_TOWN>\n            <POSTCODE>SO16 0AS</POSTCODE>\n            <RPC>2</RPC>\n            <X_COORDINATE>437318.0</X_COORDINATE>\n            <Y_COORDINATE>115539.0</Y_COORDINATE>\n            <STATUS>APPROVED</STATUS>\n            <LOGICAL_STATUS_CODE>1</LOGICAL_STATUS_CODE>\n            <CLASSIFICATION_CODE>CO01GV</CLASSIFICATION_CODE>\n            <CLASSIFICATION_CODE_DESCRIPTION>Central Government Service</CLASSIFICATION_CODE_DESCRIPTION>\n            <LOCAL_CUSTODIAN_CODE>1760</LOCAL_CUSTODIAN_CODE>\n            <LOCAL_CUSTODIAN_CODE_DESCRIPTION>TEST VALLEY</LOCAL_CUSTODIAN_CODE_DESCRIPTION>\n            <POSTAL_ADDRESS_CODE>S</POSTAL_ADDRESS_CODE>\n            <POSTAL_ADDRESS_CODE_DESCRIPTION>A single address</POSTAL_ADDRESS_CODE_DESCRIPTION>\n            <BLPU_STATE_CODE>2</BLPU_STATE_CODE>\n            <BLPU_STATE_CODE_DESCRIPTION>In use</BLPU_STATE_CODE_DESCRIPTION>\n            <TOPOGRAPHY_LAYER_TOID>osgb1000002682081995</TOPOGRAPHY_LAYER_TOID>\n            <LAST_UPDATE_DATE>01/09/2010</LAST_UPDATE_DATE>\n            <ENTRY_DATE>01/09/2010</ENTRY_DATE>\n            <BLPU_STATE_DATE>01/09/2010</BLPU_STATE_DATE>\n            <LANGUAGE>EN</LANGUAGE>\n            <MATCH>1.0</MATCH>\n            <MATCH_DESCRIPTION>EXACT</MATCH_DESCRIPTION>\n        \n        </DPA>\n    \n    </results>\n</AddressAPI>","name":"OK - XML"},{"language":"json","status":400,"code":"{\n  \"error\": {\n    \"statuscode\": 400,\n    \"message\": \"Invalid GeoJSON detected, we accept valid GeoJSON of Polygon and MultiPolygon types. Specification can be found at geojson.org.\"\n  }\n}"},{"code":"{\n  \"fault\": {\n    \"faultstring\": \"Invalid ApiKey\",\n    \"detail\": {\n      \"errorcode\": \"oauth.v2.InvalidApiKey\"\n    }\n  }\n}","language":"json","status":401},{"code":"{\n  \"error\": {\n    \"statuscode\": 404,\n    \"message\": \"Resource polygon requires POST request. GET valid resources are match, find, uprn, postcode, bbox, nearest, radius.\"\n  }\n}","language":"json","status":404},{"code":"{\n  \"fault\": {\n    \"faultstring\": \"Received 405 Response without Allow Header\",\n    \"detail\": {\n      \"errorcode\": \"protocol.http.Response405WithoutAllowHeader\"\n    }\n  }\n}","language":"text","status":405},{"status":500,"code":"{\n  \"error\": {\n    \"statuscode\": 500,\n    \"message\": \"The provided request resulted in an internal server error.\"\n  }\n}","language":"json"}]},"settings":"57a84864b1641a1700ede40d","auth":"required","params":[{"_id":"570bcb9900656917001cd55b","ref":"","in":"query","required":false,"desc":"Reference point geometry is the basis from which the distance value is calculated. Output is ordered by ascending distance from given reference point only if parameter has been specified.","default":"","type":"int","name":"referencepoint"},{"_id":"570bcb9900656917001cd55a","ref":"","in":"query","required":false,"desc":"The maximum number of results to return. Default: 100","default":"1-100","type":"string","name":"maxresults"},{"_id":"570bcb9900656917001cd558","ref":"","in":"query","required":false,"desc":"The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA","default":"DPA, LPI","type":"string","name":"dataset"},{"_id":"570bcb9900656917001cd559","ref":"","in":"query","required":false,"desc":"Offset the list of returned by this amount.","default":"","type":"int","name":"offset"},{"_id":"570bcb9900656917001cd557","ref":"","in":"query","required":false,"desc":"Which language of addresses to return. Valid languages are English and Welsh. Filter only applicable to DPA dataset. Default: EN, CY","default":"EN, CY","type":"string","name":"lr"},{"_id":"570bcb9900656917001cd556","ref":"","in":"query","required":false,"desc":"A filter that allows filtering of results by classification code and/or logical status code. Filtering for classification code will accept wildcard (*) searches. Multiple searches can be done on classification code separating the classification code parameter with a space. Classification code filters can be ran with logical status code filters by using the parameter multiple times: fq=classification_code:CI classification_code:RD&fq=LOGICAL_STATUS_CODE:6 . Valid: classification_code:[code], LOGICAL_STATUS_CODE:[code]","default":"classification_code:[code], LOGICAL_STATUS_CODE:[code]","type":"string","name":"fq"},{"_id":"570bcb9900656917001cd555","ref":"","in":"query","required":false,"desc":"The intended output spatial reference system. Default: EPSG:27700","default":"BNG, EPSG:27700, WGS84, EPSG:4326, EPSG:3857, EPSG:4258","type":"string","name":"output_srs"},{"_id":"570bcb9900656917001cd554","ref":"","in":"query","required":false,"desc":"The spatial reference system for the input coordinate set.","default":"BNG, EPSG:27700, WGS84, EPSG:4326, EPSG:3857, EPSG:4258","type":"string","name":"srs"},{"_id":"57a0b2e41435850e00dfbc57","ref":"","in":"header","required":true,"desc":"","default":"application/json","type":"string","name":"Content-Type"},{"_id":"57a0b709aa19b6200036c524","ref":"","in":"body","required":true,"desc":"The first name:value pair for the geoJSON polygon.","default":"Feature","type":"object","name":"type"},{"_id":"57a0bdc69121d42b003a9fdb","ref":"","in":"body","required":true,"desc":"Here is where the polygon object is placed.","default":"","type":"object","name":"geometry"}],"url":"/v1/addresses/polygon?"},"isReference":true,"order":8,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Vertex limit\",\n  \"body\": \"If a complex polygon comprising of more than 5000 vertices is used with the reference point attribute, the service may time out.\"\n}\n[/block]","excerpt":"","slug":"os-places-polygon","type":"endpoint","title":"Polygon"}

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

referencepoint:
integer
Reference point geometry is the basis from which the distance value is calculated. Output is ordered by ascending distance from given reference point only if parameter has been specified.
maxresults:
string1-100
The maximum number of results to return. Default: 100
dataset:
stringDPA, LPI
The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA
offset:
integer
Offset the list of returned by this amount.
lr:
stringEN, CY
Which language of addresses to return. Valid languages are English and Welsh. Filter only applicable to DPA dataset. Default: EN, CY
fq:
stringclassification_code:[code], LOGICAL_STATUS_CODE:[code]
A filter that allows filtering of results by classification code and/or logical status code. Filtering for classification code will accept wildcard (*) searches. Multiple searches can be done on classification code separating the classification code parameter with a space. Classification code filters can be ran with logical status code filters by using the parameter multiple times: fq=classification_code:CI classification_code:RD&fq=LOGICAL_STATUS_CODE:6 . Valid: classification_code:[code], LOGICAL_STATUS_CODE:[code]
output_srs:
stringBNG, EPSG:27700, WGS84, EPSG:4326, EPSG:3857, EPSG:4258
The intended output spatial reference system. Default: EPSG:27700
srs:
stringBNG, EPSG:27700, WGS84, EPSG:4326, EPSG:3857, EPSG:4258
The spatial reference system for the input coordinate set.

Body Params

type:
required
objectFeature
The first name:value pair for the geoJSON polygon.
geometry:
required
object
Here is where the polygon object is placed.

Headers

Content-Type:
required
stringapplication/json

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "title": "Vertex limit", "body": "If a complex polygon comprising of more than 5000 vertices is used with the reference point attribute, the service may time out." } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}