{"_id":"55e06a82186ca30d00f9b446","category":{"_id":"55e970cc358d923700be9853","pages":[],"version":"55e06495a44fae0d002146ad","__v":0,"project":"55e06494a44fae0d002146aa","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-04T10:22:04.162Z","from_sync":false,"order":12,"slug":"endpoint-1","title":"endpoint"},"editedParams":true,"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"},"user":"55e056b06bad670d0081f234","editedParams2":true,"project":"55e06494a44fae0d002146aa","__v":3,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-08-28T14:04:50.831Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","code":"var req = new XMLHttpRequest();\nreq.open(\"GET\", \"https://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton&key=[[app:key]]\",true);\n\nreq.onreadystatechange = function () {\n    console.log(req.responseText);\n}\nreq.send();","language":"javascript"},{"code":"var url = 'https://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton&key=[[app:key]]';\n\n$.getJSON(url, function(data){\n    console.log(data);\n})","language":"javascript","name":"JQuery"},{"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\tvar osAPI = angular.module('angularAPI', []);\n\n\tosAPI.controller('apiService', ['$scope', '$http', function($scope, $http) {\n\t\tvar key = \"[[app:key]]\";\n\t\tvar query = 'https://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton';\n\t\t$http.get(query+'&key='+key).success(function(data) {\n\t\t\t$scope.output = data.results;\n\t\t});\n\t}]);\n</script>\n\n<body ng-controller=\"apiService\">\n\t<ul ng-repeat=\"value in output\">\n\t\t<li ng-repeat=\"object in value\">\n\t\t\t<p>{{object}}</p>\n\t\t</li>\n\t</ul>\n</body>\n</html>","language":"html","name":"AngularJS"},{"name":"Node.js","code":"var https = require('https');\n\nhttps.get(\"https://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton&key=[[app:key]]\", function(res) {\n  console.log(\"Got response: \" + res.statusCode);\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n}).on('error', function(e) {\n  console.log(\"Got error: \" + e.message);\n});","language":"javascript"},{"code":"<?php\n\t$curl = curl_init();\n    curl_setopt ($curl, CURLOPT_URL, \"https://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton&key=[[app:key]]\");\n    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);\n\n    $result = curl_exec ($curl);\n    curl_close ($curl);\n    print \"<pre>$result\";\n?>","language":"php","name":"PHP"}]},"method":"get","results":{"codes":[{"code":"{\n  \"header\" : {\n    \"uri\" : \"https://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton&maxresults=1\",\n    \"query\" : \"Southampton\",\n    \"format\" : \"JSON\",\n    \"maxresults\" : 1,\n    \"offset\" : 0,\n    \"totalresults\" : 5191\n  },\n  \"results\" : [ {\n    \"GAZETTEER_ENTRY\" : {\n      \"ID\" : \"osgb4000000074564709\",\n      \"NAMES_URI\" : \"http://data.ordnancesurvey.co.uk/id/osgb4000000074564709\",\n      \"NAME1\" : \"Southampton\",\n      \"TYPE\" : \"populatedPlace\",\n      \"LOCAL_TYPE\" : \"City\",\n      \"GEOMETRY_X\" : 441982.48,\n      \"GEOMETRY_Y\" : 111881.99,\n      \"MOST_DETAIL_VIEW_RES\" : 73000,\n      \"LEAST_DETAIL_VIEW_RES\" : 9000000,\n      \"MBR_XMIN\" : 436728.894,\n      \"MBR_YMIN\" : 109121.504,\n      \"MBR_XMAX\" : 447910.211,\n      \"MBR_YMAX\" : 118903.114,\n      \"POSTCODE_DISTRICT\" : \"SO14\",\n      \"POSTCODE_DISTRICT_URI\" : \"http://data.ordnancesurvey.co.uk/id/postcodedistrict/SO14\",\n      \"COUNTY_UNITARY\" : \"City of Southampton\",\n      \"COUNTY_UNITARY_URI\" : \"http://data.ordnancesurvey.co.uk/id/7000000000037256\",\n      \"COUNTY_UNITARY_TYPE\" : \"http://data.ordnancesurvey.co.uk/ontology/admingeo/UnitaryAuthority\",\n      \"REGION\" : \"South East\",\n      \"REGION_URI\" : \"http://data.ordnancesurvey.co.uk/id/7000000000041421\",\n      \"COUNTRY\" : \"England\",\n      \"COUNTRY_URI\" : \"http://data.ordnancesurvey.co.uk/id/country/england\",\n      \"SAME_AS_GEONAMES\" : \"http://sws.geonames.org/2637487\"\n    }\n  } ]\n}","language":"json","status":200,"name":"JSON"},{"status":200,"code":"<places>\n\t<header>\n\t\t<uri>\nhttps://api.ordnancesurvey.co.uk/opennames/v1/find?query=Southampton&maxresults=1&format=xml\n\t\t</uri>\n\t\t<query>Southampton</query>\n\t\t<format>xml</format>\n\t\t<maxresults>1</maxresults>\n\t\t<offset>0</offset>\n\t\t<totalresults>5191</totalresults>\n\t</header>\n\t<results>\n\t\t<GAZETTEER_ENTRY>\n\t\t\t<ID>osgb4000000074564709</ID>\n\t\t\t<NAMES_URI>\nhttp://data.ordnancesurvey.co.uk/id/osgb4000000074564709\n\t\t\t</NAMES_URI>\n\t\t\t<NAME1>Southampton</NAME1>\n\t\t\t<TYPE>populatedPlace</TYPE>\n\t\t\t<LOCAL_TYPE>City</LOCAL_TYPE>\n\t\t\t<GEOMETRY_X>441982.48</GEOMETRY_X>\n\t\t\t<GEOMETRY_Y>111881.99</GEOMETRY_Y>\n\t\t\t<MOST_DETAIL_VIEW_RES>73000</MOST_DETAIL_VIEW_RES>\n\t\t\t<LEAST_DETAIL_VIEW_RES>9000000</LEAST_DETAIL_VIEW_RES>\n\t\t\t<MBR_XMIN>436728.894</MBR_XMIN>\n\t\t\t<MBR_YMIN>109121.504</MBR_YMIN>\n\t\t\t<MBR_XMAX>447910.211</MBR_XMAX>\n\t\t\t<MBR_YMAX>118903.114</MBR_YMAX>\n\t\t\t<POSTCODE_DISTRICT>SO14</POSTCODE_DISTRICT>\n\t\t\t<POSTCODE_DISTRICT_URI>\nhttp://data.ordnancesurvey.co.uk/id/postcodedistrict/SO14\n\t\t\t</POSTCODE_DISTRICT_URI>\n\t\t\t<COUNTY_UNITARY>City of Southampton</COUNTY_UNITARY>\n\t\t\t<COUNTY_UNITARY_URI>\nhttp://data.ordnancesurvey.co.uk/id/7000000000037256\n\t\t\t</COUNTY_UNITARY_URI>\n\t\t\t<COUNTY_UNITARY_TYPE>\nhttp://data.ordnancesurvey.co.uk/ontology/admingeo/UnitaryAuthority\n\t\t\t</COUNTY_UNITARY_TYPE>\n\t\t\t<REGION>South East</REGION>\n\t\t\t<REGION_URI>\nhttp://data.ordnancesurvey.co.uk/id/7000000000041421\n\t\t\t</REGION_URI>\n\t\t\t<COUNTRY>England</COUNTRY>\n\t\t\t<COUNTRY_URI>\nhttp://data.ordnancesurvey.co.uk/id/country/england\n\t\t\t</COUNTRY_URI>\n\t\t\t<SAME_AS_GEONAMES>http://sws.geonames.org/2637487</SAME_AS_GEONAMES>\n\t\t</GAZETTEER_ENTRY>\n\t</results>\n</places>","language":"xml","name":"XML"},{"code":"// Example: Missing mandatory parameter\n{\n  \"error\" : {\n    \"statuscode\" : 400,\n    \"message\" : \"No query parameter provided.\"\n  }\n}\n\n// Example: Parameter entry of wrong type\n{\n  \"error\" : {\n    \"statuscode\" : 400,\n    \"message\" : \"Parameter maxresults contains invalid characters. Valid characters are numeric.\"\n  }\n}\n\n// Example: Wrong parameter name\n{\n  \"error\" : {\n    \"statuscode\" : 400,\n    \"message\" : \"Parameter x is not a valid parameter for resource find. Valid parameters for requested resource are query, format, maxresults, offset, bounds, fq.\"\n  }\n}","language":"json","status":400,"name":""},{"code":"{\n    \"fault\": {\n        \"faultstring\": \"Invalid ApiKey\",\n        \"detail\": {\n            \"errorcode\": \"oauth.v2.InvalidApiKey\"\n        }\n    }\n}","language":"json","status":401},{"language":"json","status":404,"code":"{\n     \"error\": {\n         \"statuscode\": \"404\",\n         \"message\": \"Resource x does not exist. Valid resources are find, nearest.\"\n     }\n}"},{"code":"{  \n   \"fault\":{  \n      \"faultstring\":\"Received 405 Response without Allow Header\",\n      \"detail\":{  \n         \"errorcode\":\"protocol.http.Response405WithoutAllowHeader\"\n      }\n   }\n}","language":"json","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":"55e972ed461e2a390050f22f","auth":"required","params":[{"_id":"55e0825758c5460d0076aa40","ref":"","in":"query","required":true,"desc":"The free text search parameter","default":"","type":"string","name":"query"},{"_id":"55e975a28b72bb3700b1d5b4","ref":"","in":"query","required":false,"desc":"The format the response will be returned in. Default: JSON.","default":"JSON, XML","type":"string","name":"format"},{"_id":"55e975a28b72bb3700b1d5b3","ref":"","in":"query","required":false,"desc":"The maximum number of results to return. Default: 100.","default":"1-100","type":"int","name":"maxresults"},{"_id":"55e975a28b72bb3700b1d5b2","ref":"","in":"query","required":false,"desc":"Offset the list of returned by this amount.","default":"","type":"int","name":"offset"},{"_id":"55e975a28b72bb3700b1d5b1","ref":"","in":"query","required":false,"desc":"Biases the results to a certain area. The <BoundingBox> is a British National Grid bounding box in the form: XMIN,YMIN,XMAX,YMAX e.g. &bounds=414000,114000,414100,114100","default":"<BoundingBox>","type":"string","name":"bounds"},{"_id":"55e975a28b72bb3700b1d5b0","ref":"","in":"query","required":false,"desc":"Filters the results by bounding box or local_type. The bounding box is a British National Grid bounding box in the form: XMIN,YMIN,XMAX,YMAX e.g. &fq=BBOX:414000,114000,414100,114100. Available local types are <a href=\"https://apidocs.os.uk/docs/os-names-content\">here</a>","default":"local_type:<local type>","type":"string","name":"fq"}],"url":"/v1/find?"},"isReference":true,"order":0,"body":"The OS OpenNames Github repo contains examples and snippets for various languages and plugins.\n[block:embed]\n{\n  \"html\": false,\n  \"url\": \"https://github.com/OrdnanceSurvey/OS-Open-Names\",\n  \"title\": \"OrdnanceSurvey/OS-Open-Names\",\n  \"favicon\": \"https://assets-cdn.github.com/favicon.ico\",\n  \"image\": \"https://avatars1.githubusercontent.com/u/2436924?v=3&s=400\"\n}\n[/block]","excerpt":"OS Names Find","slug":"os-names-find","type":"endpoint","title":"Find"}

getFind

OS Names Find

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

query:
required
string
The free text search parameter
format:
stringJSON, XML
The format the response will be returned in. Default: JSON.
maxresults:
integer1-100
The maximum number of results to return. Default: 100.
offset:
integer
Offset the list of returned by this amount.
bounds:
string<BoundingBox>
Biases the results to a certain area. The <BoundingBox> is a British National Grid bounding box in the form: XMIN,YMIN,XMAX,YMAX e.g. &bounds=414000,114000,414100,114100
fq:
stringlocal_type:<local type>
Filters the results by bounding box or local_type. The bounding box is a British National Grid bounding box in the form: XMIN,YMIN,XMAX,YMAX e.g. &fq=BBOX:414000,114000,414100,114100. Available local types are <a href="https://apidocs.os.uk/docs/os-names-content">here</a>

Examples


Result Format


Documentation

The OS OpenNames Github repo contains examples and snippets for various languages and plugins. [block:embed] { "html": false, "url": "https://github.com/OrdnanceSurvey/OS-Open-Names", "title": "OrdnanceSurvey/OS-Open-Names", "favicon": "https://assets-cdn.github.com/favicon.ico", "image": "https://avatars1.githubusercontent.com/u/2436924?v=3&s=400" } [/block]

User Information

Try It Out

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