Web Service User Guide - One Scotland Gazetteer Home
Contents
1. DK OneScotland accessing public services Or it can be in addition to one or more attribute elements for example lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Header gt lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt lt ns query gt lt dataset gt BLPU lt dataset gt lt attribute gt lt name gt Logical Status lt name gt lt value gt 8 lt value gt lt attribute gt area 1 Loch Lomond NPA lt area gt lt ns query gt lt SoapEnv Body lt SoapEnv Envelope gt This for example would return all historical BLPUs contained within the area defined by the Loch Lomond polygon If successful which could include returning zero results the web service returns a set of elements as described in the earlier attribute search section On failure it returns an error code and message For example if the user were to supply a name which does not match any polygon in the system they would receive the following response lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Body gt lt ns SearchResponseMessage gt lt NGSearchResponseData gt lt Header gt lt ResultCount gt 0 lt ResultCount gt lt ReturnCount gt 0 lt ReturnCount gt lt ErrorCode gt 2 lt Er2. DK OneScotland accessing public services Col UPRN Col lt NGListDataSetsResponseData gt lt NGListDataSetsResponseData gt lt DataSet gt BLPU lt DataSet gt lt Col gt BLPU_State lt Col gt Corl BLEU State Date lt Col gt Col Custodian Code Col lt Col gt End_Date lt Col gt lt Col gt Entry Dare Col Col Last Update Date lt Col gt Col Logical Status Col lt Col gt Parent_UPRN lt Col gt lt Col gt RPC lt Col gt lt Col gt Start_Date lt Col gt Col UPRN Col lt Col gt X_Coordinate lt Col gt lt Col gt Y_Coordinate lt Col gt lt NGListDataSetsResponseData gt lt ns ListDataSetsResponseMessage gt lt SoapEnv Body gt lt SoapEnv Envelope gt es The response consists of a ListDataSetsResponseMessage element which contains one or more NGListDataSetsResponseData elements Each of these elements contains information about an individual dataset The name of the dataset is contained within a DataSet element whilst each column in that dataset is identified by a Col element So in this example there are two datasets defined one called ADDRESSES and one called BLPU The ADDRESSES dataset contains columns such as Custodian Easting and Locality whilst the BLPU dataset contains columns such as BLPU State BLPU State Date and Custodian Code 2 4 Query a Dataset sendNGSearchMessage The sendNGSearchMessage all
3. enum e equal to default greater than greater than or equal to less than less than or equal to not equal to contains between in not in SortOrderType enum e asc default e desc EastingType unsignedLong with restriction minInclusive 0 maxInclusive 500000 NorthingType unsignedLong with restriction minInclusive 500000 maxlInclusive 1300000 3 1 5 Output NGSearchResponsePart type SearchResponseMessage e NGSearchResponseData type SearchResponseType o Header type SearchResponseHeaderType ResultCount type nonNegativelnteger ReturnCount type nonNegativelnteger J ErrorCode type ErrorCode Type ErrorMessage type ErrorMessageType o Result type SearchResponseResultType ResultCount The number of data items found which match the query ReturnCount The number of data items returned by the web service the minimum of ResultCount and 250 ErrorCode Zero for success or non zero for failure see later ErrorMessage A message describing an error which occurred see later Result The data items matching the query The actual format will depend on the dataset being queried but it will consist of a set of elements named the same as the dataset each element containing an DK OneScotland accessing public services element for each field in the dataset named the same as that field ErrorCodeType type integer with restriction minInclusive 0 maxlInclusive 9999 ErrorMessageType type string with restriction ma
4. o distance type decimal e sortField optional type string e SortOrder optional type SortOrderType dataset attribute area The name of the dataset to be queried by the web service One or more attributes of the dataset which can be used for filtering the results to be returned The attributes specified must be from the fields in the dataset A matchtype can be specified see below for list with equal to being the default All comparisons are case insensitive For the attribute being specified a name of the field and one or more values must be supplied Multiple attributes are applied in turn to produce smaller sets of results to be returned i e they are logically anded together This takes the name of a pre loaded polygon which can be used to restrict results to items with a UPRN in a geographical area defined by that polygon DK OneScotland gt accessing public services within If this element is supplied then it must contain three sub elements an easting a northing and a distance These elements define an area and only items with a UPRN in that area are returned sortField This allows the results to be sorted on one of the fields from the dataset The value supplied for this must be one of the fields from the dataset sortOrder This takes a value of either asc for ascending or desc for descending and is applied to the sortField If no sortOrder is supplied ascending is used as the default MatchType
5. ns SearchResponseMessage gt lt SoapEnv Body gt lt SoapEnv Envelope gt DK OneScotland accessing public services This indicates that 2 197 410 matches were found the ResultCount It also indicates that if a full request were being made only 250 of those results would be returned the ReturnCount Although this example is a basic request for all elements in a dataset the type header attribute can be added to any query such as those discussed earlier in this section DK OneScotland accessing public services 3 Appendices 3 1 Search Request XML sendNGSearchMessage 3 1 1 Description Main entry point into the National Gazetteer Address Search Service Address search messages should be sent here for the National Gazetteer to process 3 1 2 Operation type Request response The endpoint receives a message and sends a correlated message 3 1 3 SOAP action http www scottishcitizen gov uk improvementservice nationalinfrastructure addresssearch sendNGSearchMessag 3 1 4 Input NGSearchRequestPart type query e dataset mandatory type string e attribute optional unbounded type Attribute Type matchtype optional attribute type MatchType name type string o value unbounded type string e area optional type string e within optional type Within Type easting type Easting Type northing type NorthingType
6. datasets and the fields which those datasets contain The web service takes no parameters but does require authentication as discussed earlier lt Soap xm SIS Env Envelope lns SoapEnv http schemas xmlsoap org soap envelope xm nationalinfrastructure addresssearch v0 1 gt lt SoapEnv Header gt lt ns lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt Ins ns http www scottishcitizen gov uk improvementservice HeaderLogin gt lt SoapEnv Body gt listdatasets gt lt SoapEnv Body SoapEnv Envelope Here is an example of what such a call might return note that future examples will omit the namespace URLs Soap Env Envelope xmlns SoapEnv xmlns ns gt Beers SoapEnv Body ListDataSetsResponseMessage lt NGListDataSetsResponseData gt lt DataSet gt ADDRESSES lt DataSet gt lt Col gt Custodian lt Col gt lt Col gt Easting lt Col gt lt Col gt Locality lt Col gt Col Logical Status lt Col gt lt Col gt Northing lt Col gt lt Col gt PAO Num lt Col gt lt Col gt PAO_Text lt Col gt lt Col gt PostTown lt Col gt lt Col gt Postcode lt Col gt lt Col gt SAO_ Num Col lt Col gt SAO_Text lt Col gt lt Col gt Street lt Col gt lt Col gt Town lt Col gt
7. gt K OneScotland accessing public services OneScotland Gazetteer Web Service User Guide Document Version 0 1 Date July 2010 2 3 DK OneScotland accessing public services SII eege eene Ee egen ee 3 Web SEWICES oii alesis arataa EN un daea AAE EEES p EANN GEE EE UN EENS AEE 3 2 1 OVEN IEW anana eai E Ee EE EEEE edu 3 22 LtEtt Le ME 3 2 3 List Datasets GendhNGlietiatatetsMessagel 4 2 4 Query a Dataset sendNGSearchMessage sssesseeesresiresrresrrssrrssrrssrrssrrssrrssrns 5 2 4 1 Return a Full Dataset eee cence center eeeeeeeeeeeeaeeeeeeaaeeeeeeaaeeeeeeaaeeeeeeaaeeeeeeaas 5 2 4 2 Attribute Based Searches sse nnne 7 2 4 8 Combined Searches sss ener ener enne nns 11 2 4 4 Spatial Based Gearches sse nnns 11 2 4 4 1 Polygon Based Searches sse 11 2 4 4 2 Combined Area Searches sss eene 13 2 4 4 8 Radius Based Searches sss eene 13 2 4 5 Ordering of Results esses esent nennen nnns 14 2 4 6 Returning a Count of Matches sse nennen 15 Perez EE 17 3 1 Search Request XML eendhGGearchMeseagel 17 SLT RT lee eet eR Pr ed ERREUR RENE REOR ERR eee 17 3 12 Operation type eee rb eene REX Y etn ee EENS EE RENE Eu 17 ox EMO UI Em 17 CX MEMO E 17 on P EEG Uso MEE 18 3 2 UE BIEN 19 32 1 WSDL URL Em 19 3 2 2 WSDL COmEeni eccrine n E E Ee 19 DK OneScotland accessing public services 1 Overview These web services allow access to the data stored in
8. as indicated by both the ResultCount and ReturnCount elements It is worth noting briefly what happens in a failure situation Suppose that we omitted the last digit from the UPRN we supplied as a value In that case the response would be as follows lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Body gt lt ns SearchResponseMessage gt lt NGSearchResponseData gt lt Header gt DK OneScotland accessing public services lt ResultCount gt 0 lt ResultCount gt lt ReturnCount gt 0 lt ReturnCount gt lt ErrorCode gt 0 lt ErrorCode gt lt ErrorMessage gt Success lt ErrorMessage gt lt Header gt lt Result gt lt Result gt lt NGSearchResponseData gt lt ns SearchResponseMessage gt lt SoapEnv Body gt lt SoapEnv Envelope gt This shows that the query was successfully executed as indicated by the ErrorCode and the ErrorMessage but that it returned no results the ResultCount is zero and the Result element contains no sub elements It is also possible for a query to fail if an unexpected error was encountered A UPRN should be numeric If therefore a non numeric UPRN were to be supplied the web service would instead return a result similar to the following SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Body gt lt ns SearchResponseMessage gt lt NGSearc
9. e gt lt value gt STIRLING lt value gt lt attribute gt lt attribute gt lt name gt Logical Status lt name gt lt value gt 8 lt value gt lt attribute gt lt ns query gt 2 4 4 Spatial Based Searches In addition to searching by attribute it is also possible to restrict results using spatial searches These allow searches to be constrained to a given polygon or within a radius of a point 2 4 4 4 Polygon Based Searches This allows the restriction of results to an area as defined by a polygon Such areas must already be loaded into the system i e they cannot be supplied as part of the web service and are referred to by name So for example suppose that there exists within the database a polygon named Loch Lomond This can then be used to limit the results returned to only those within that polygon To limit results to a named polygon an area element must be added to a query this can either be instead of any attribute elements for example SSodpBmnvBmwelopevmlmsesodpEmwv eU scmiltmsismise TM SoapEnv Header lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt lt ns query gt lt dataset gt BLPU lt dataset gt lt area gt l Loch Lomond NPA lt area gt lt ns query gt lt SoapEnv Body lt SoapEnv Envelope gt
10. ence gt lt xsd element name NGSearchResponseData type SearchResponseType gt lt xsd sequence gt lt xsd complexType gt lt xsd element gt xsd complexType name SearchResponseType gt DK OneScotland accessing public services lt xsd sequence gt lt xsd element name Header type SearchResponseHeaderType gt lt xsd element name Result type SearchResponseResultType gt xsd sequence xsd complexType xsd complexType name SearchResponseHeaderType gt lt xsd sequence gt lt xsd element name ResultCount type xsd nonNegativeInteger lt xsd element name ReturnCount type xsd nonNegativeInteger xsd element name ErrorCode type ErrorCodeType xsd element name ErrorMessage type ErrorMessageType xsd sequence xsd complexType xsd complexType name SearchResponseResultType gt xsd sequence xsd any minOccurs 0 xsd sequence xsd complexType lt xsd element name SearchException lt xsd complexType gt lt xsd sequence gt lt xsd complexType gt lt xsd element gt lt xsd simpleType name ErrorCodeType gt lt xsd restriction base xsd integer gt xsd minInclusive value 0 gt lt xsd maxInclusive value 9999 gt lt xsd restriction gt lt xsd simpleType gt lt xsd simpleType name ErrorMessageType gt lt xsd restriction base xsd string gt lt xsd maxLength value 200 gt lt xsd minLength value 1
11. gt lt xsdi restrict on lt xsd simpleType gt lt xsd element name ListDataSetsResponseMessage gt lt xsd complexType gt lt xsd sequence gt lt xsd element minOccurs 0 maxOccurs unbounded name NGListDataSetsResponseData type ListDataSetsResponseType gt xsd sequence xsd complexType lt xsd element gt lt xsd complexType name ListDataSetsResponseType gt lt xsd sequence gt lt xsd element name DataSet type xsd string gt lt xsd element minOccurs 1 maxOccurs unbounded name Col type xsd string gt xsd sequence xsd complexType xsd schema types message name HeaderLoginMessage gt part name HeaderLogin element tns HeaderLogin gt message message name NGSearchMessageSoapIn part name NGSearchRequestPart element tns query message message name NGSearchMessageSoapOut gt lt part name NGSearchResponsePart element tns SearchResponseMessage message message name NGSearchFaultSoap gt part name NGSearchFaultDetail element tns SearchException gt message message name NGListDataSetsMessageSoapIn gt DK OneScotland accessing public services lt part name NGListDataSetsRequestPart element tns listdatasets gt lt message gt message name NGListDataSetsMessageSoapOut part name NGListDataSetsResponsePart element tns ListDataSetsRe
12. gt UPRN lt name gt lt value gt 906255606 lt value gt lt attribute gt lt ns query gt SoapEnv Body lt SoapEnv Envelope gt This is telling the web service to use the dataset BLPU and to only return values where the UPRN is equal to 906255606 The web service will return a response similar to the following lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Body gt lt ns SearchResponseMessage gt lt NGSearchResponseData gt lt Header gt lt ResultCount gt 1 lt ResultCount gt lt ReturnCount gt 1 lt ReturnCount gt lt ErrorCode gt 0 lt ErrorCode gt lt ErrorMessage gt Success lt ErrorMessage gt lt Header gt lt Result gt lt BLPU gt UPRN gt 906255606 lt UPRN gt Logical Status gt 1 lt Logical Status gt X Coordinate 325193 X Coordinate Goose e ee RPC gt 1 lt RPC gt Custodian Code gt 9064 lt Custodian_ Code Start Dare gt 1993 00 30 lt 9rart_ Date Last Update Date 2008 11 28 Last Update Date lt Entry Date 1993 08 30 lt Eatry Date lt BLPU gt lt Result gt lt NGSearchResponseData gt lt ns SearchResponseMessage gt lt SoapEnv Body gt SoapEnv Envelope IN is IK IK IN IS A AN This is in exactly the same format as the earlier example of a response They obvious difference is that it now only contains one result
13. hResponseData gt lt Header gt lt ResultCount gt 0 lt ResultCount gt lt ReturnCount gt 0 lt ReturnCount gt lt ErrorCode gt 2 lt ErrorCode gt lt ErrorMessage gt UPRN Invalid Number 90625560X lt ErrorMessage gt lt Header gt lt Result gt lt Result gt lt NGSearchResponseData gt lt ns SearchResponseMessage gt lt SoapEnv Body gt lt SoapEnv Envelope gt The difference between this and the previous example is that there is now an ErrorCode and corresponding ErrorMessage which indicates a failure of the web service to execute This is an important distinction to make since the web service may indicate a successful result which is contrary to user expectations The web service considers a query to be a success even if it returns zero matches It will only consider a query to have failed if it cannot execute at all Use of the attribute element in this way allows either a single data item to be found as illustrated above or multiple data items for example if the attribute was Logical_Status and the value we supplied was 8 then it would return all historic BLPUs However only being able to test for equality is very limiting It is therefore possible to test attributes in other ways Consider our earlier example ns query lt dataset gt BLPU lt dataset gt lt attribute gt lt name gt UPRN lt name gt DK OneScotland accessing
14. ill be situations in which it is useful to return all results in a dataset for example reporting web services such as a dataset containing each Custodian and the number of BLPUs they have supplied However in most situations users will want to reduce the number of matches returned by providing some sort of search parameters To achieve this it is possible to supply attributes and conditions to select subsets of a dataset Within the query element of the web service the caller can supply one or more attribute elements These attribute elements contain a name element the name of the column that the test is against and one or more value elements being the value or values used within the test Consider a user who wishes to retrieve the information for a specific BLPU for which they know the UPRN They simply need to add an attribute to their query element which contains a name element of UPRN and a value element containing the UPRN they are interested in for example 906255606 The SOAP request for this would therefore be SoapEnv Envelope xmlns SoapEnv xmlns ns gt SoapEnv Header lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt DK OneScotland accessing public services lt ns HeaderLogin gt SoapEnv Header lt SoapEnv Body gt lt ns query gt lt dataset gt BLPU lt dataset gt lt attribute gt lt name
15. lt NGSearchResponseData gt lt Header gt lt ResultCount gt 2824436 lt ResultCount gt lt ReturnCount gt 250 lt ReturnCount gt lt ErrorCode gt 0 lt ErrorCode gt lt ErrorMessage gt Success lt ErrorMessage gt lt Header gt lt Result gt CONTENT OMITTED HERE SEE LATER Result NGSearchResponseData ns SearchResponseMessage SoapEnv Body SOAP ENV Envelope The data returned is contained within an NGSearchResponseData element which is in turn contained within a SearchResponseMessage element The NGSearchResponseData contains two elements Header and Result The Header element contains information about the results returned notably how many and the Result element contains the actual data resulting from the query Within the Header element there are the following elements e ResultCount How many matches were actually found in this example there are 2 824 436 BLPUs in the dataset e ReturnCount How many of those matches are included in this response This will either be 250 the limit on results returned or the same as ResultCount if there are less matches than 250 e ErrorCode A number indicating if an error was encountered with 0 representing a successful query e ErrorMessage A textual indication of any errors encountered or Success if no errors occurred The result element contains an element for each resu
16. lt returned i e the same number of elements as the value of the ReturnCount element in the Header element Result lt BLPU gt lt UPRN gt 906255606 lt UPRN gt XLogical totus l Logical Status gt 74 OneScotland i accessing public services x Coordinate 329193 X Coordinate Y Coordinate 673285 Y Coordinate RPC gt 1 lt RPC gt Custodian Code gt 9064 lt Custodian Code Start Dato ee 06 390 Sheeseie Dater Last Update Date 22008 11 28 Last Update Date Torey Denes EE BLPU gt LPU gt UPRN gt 906255607 lt UPRN gt Logical Status 1 Logical Status gt X Coordinate 325160 X Coordinate Y Coordinate gt 03276 lt Y_Coordinate gt RPC gt 1 lt RPC gt Custodian Code gt 9064 lt Custodian Code Start Dace EE Ee DEE Last Update Date gt 1993 08 30 lt Last Update Date Entry Darel ONS OS s0 lt mmicey Desc lt BLPU gt A A AA RARBRAARABDRAAAAA FURTHER RESULTS OMITTED lt Result gt Each element within the Result has the same name as the dataset being queried BLPU in this example Each of these elements contains a set of elements one for each column within the dataset and with the same name as that column name For example within the BLPU dataset there is a UPRN column so in the results there is a BLPU element for each match returned and within that BLPU element there is a UPRN element 2 4 2 Attribute Based Searches There w
17. n that polygon will be returned The radius based search is invoked by adding a within element to the query which contains an easting element a northing element and a distance element For example lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt DK OneScotland gt accessing public services SoapEnv Header lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt SoapEnv Header lt SoapEnv Body gt lt ns query gt lt dataset gt ADDRESSES lt dataset gt lt within gt lt easting gt 279717 lt easting gt lt northing gt 692958 lt northing gt lt distance gt 50 lt distance gt lt within gt lt ns query gt lt SoapEnv Body gt lt SoapEnv Envelope gt The within element can be used by itself as in the above example or can be combined with other elements in the query If a within element is added to a query then the response will contain an additional element called Distance which is not part of the data set This element contains for each record the distance of that item from the point specified by the easting and northing This can be retrieved like any field from the dataset Notably it can also be specified in a sortField element allowing the results to be returned closest first or furthest first 2 4 5 Ordering of Resul
18. n the named polygon If a user attempts to query a dataset which does not contain a UPRN an error will be returned by the web service 2 4 4 2 Combined Area Searches Multiple area elements can be included in a dataset query and follow the same principle as combining other elements Each additional area element forms an additional restriction on the results to be returned So a query containing the two elements lt area gt Areal lt area gt lt area gt Area2 lt area gt would only return values which are in both Area and Area So for example if Areal is a council boundary and Area2 is all the conservation areas in Scotland then such a query would return properties in conservation areas in that council area A query can also use a not in matchtype on any or all area elements So to continue the above example we could identify all properties within a council boundary which are not in a conservation area using the following query lt area gt Areal lt area gt area matchtype not in gt Area2 lt area gt 2 4 4 3 Radius Based Searches In a web service call the user can supply a point defined by an easting and a northing and a radius defined in metres This will restrict results returned to those within that radius As with polygon based searches this will only work with a data set which contains a UPRN field Any records in the data set which contain a UPRN field which represents a BLPU withi
19. ows the user to query a dataset limiting the results returned based on the data contained within the columns of that dataset For example if the BLPU dataset has a Last Update Date column then that could be used to identify any addresses which have been updated in the last month A query element must be provided for all calls to this web service The query element requires a mandatory element dataset the name of the dataset to be queried 2 4 1 Return a Full Dataset The simplest query which can be submitted simply asks for all information in a dataset and just consists of the query element and the dataset element together with the user authentication elements SoapEnv Envelope xmlns SoapEnv xmlns ns SoapEnv Header lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt DK OneScotland accessing public services lt ns query gt lt dataset gt BLPU lt dataset gt lt ns query gt lt SoapEnv Body SoapEnv Envelope This example will return the first 250 records in the BLPU dataset records returned from a dataset are limited to the first 250 The response will be in the following format SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Body gt lt ns SearchResponseMessage gt
20. pe xsd string gt lt xsd element name password type xsd string gt amp sexgle exl 1 lt xsd complexType gt lt xsd element gt lt xsd simpleType name SortOrderType gt lt xsd restriction base xsd string gt lt xsd enumeration value asc gt lt xsd enumeration value desc gt lt xsd restriction gt xsd simpleType xsd simpleType name MatchType gt xsd restriction base xsd string gt xsd enumeration value equal to xsd enumeration value greater than xsd enumeration value greater than or equal to xsd enumeration value less than gt 4 OneScotland accessing public services lt xsd enumeration value less than or equal to gt lt xsd enumeration value not equal to gt lt xsd enumeration value contains gt xsd enumeration value starts with gt xsd enumeration value between gt xsd enumeration value in xsd enumeration value not in lt xsd restriction gt xsd simpleType xsd simpleType name EastingType xsd restriction base xsd unsignedLong gt xsdismuimntncelusiwe value 0 gt xsd maxInclusive value 500000 xsd restriction xsd simpleType xsd simpleType name NorthingType xsd restriction base xsd unsignedLong gt xsd minInclusive value 500000 xsd maxInclusive value 1300000 lt xsd restriction gt lt xsd simpleType gt xsd complexType name Attribu
21. public services lt value gt 906255606 lt value gt lt attribute gt lt ns query gt This actually uses a special form of the attribute element The full form of the attribute element also contains a matchtype within it Our example above could be expanded as lt ns query gt lt dataset gt BLPU lt dataset gt lt attribute matchtype equal to lt name gt UPRN lt name gt lt value gt 906255606 lt value gt EE lt ns query gt By supplying other values for matchtype different tests can be used although if no matchtype is supplied it defaults to equal to as illustrated earlier The possible values of matchtype are equal to this is a case insensitive exact match greater than greater than or equal to less than less than or equal to not equal to in not in between starts with this is case insensitive contains this is case insensitive Depending on the matchtype one or more value elements will need to be supplied For equal to greater than greater than or equal to less than less than or equal to not equal to starts with and contains exactly one value element should be supplied If the match type is in or not in one or more value elements should be supplied So the following example will select all BLPUs where the Logical Status is 1 5 or 6 attribute matchtype in gt name Logical Status lt name gt lt value gt 1 lt value gt l
22. rorCode gt lt ErrorMessage gt Invalid area X Loch Lomond NPA lt ErrorMessage gt lt Header gt lt Result gt lt Result gt lt NGSearchResponseData gt lt ns SearchResponseMessage gt lt SoapEnv Body gt lt SoapEnv Envelope gt It is also possible to find all elements which are outside the polygon The area tag can take a matchtype qualifier just like the attribute tag For the area tag the possible values of matchtype are in and not in If no matchtype is supplied as in the examples above the default is in To find all BLPUs outside the Loch Lomond area the following request could be made lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Header gt lt ns HeaderLogin gt DK OneScotland accessing public services lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt lt ns query gt lt dataset gt BLPU lt dataset gt area matchtype not in gt 1 Loch Lomond NPA lt area gt lt ns query gt lt SoapEnv Body gt lt SoapEnv Envelope gt The spatial searches will only work on a data set which contains a UPRN field It will return any data from the dataset where the UPRN for that record represents a BLPU which is withi
23. sponseMessage gt lt message gt lt portType name NGSearchIntf lt operation name sendNGSearchMessage gt lt documentation gt Main entry point into the National Gazetteer Search Service Search messages should be sent here for the National Gazetteer to process lt documentation gt input message tns NGSearchMessageSoapIn output message tns NGSearchMessageSoapOut fault name fault message tns NGSearchFaultSoap gt operation operation name sendNGListDataSetsMessage lt documentation gt List searchable data sets provided by the National Gazetteer Search Service documentation input message tns NGListDataSetsMessageSoapIn output message tns NGListDataSetsMessageSoapOut operation portType Xbinding name SubmitMessageSoapHttp type tns NGSearchIntf lt soap binding style document transport http schemas xmlsoap org soap http operation name sendNGSearchMessage gt soap operation soapAction http www scottishcitizen gov uk improvementservice nationali nfrastructure addresssearch sendNGSearchMessage style document gt input soap body use literal lt soap header message tns HeaderLoginMessage part HeaderLogin use literal gt lt input gt sSoutput soap body use literal gt output fault name fault gt lt soap fault name fault use literal fault operation operation name sendNGListDataSe
24. t dataset attr name gt attr name gt Invalid Date lt value gt expected format YYYY MM DD attr name gt Invalid Number lt value gt Invalid area lt area gt The dataset dataset does not support filtering on area polygon area awaiting initial index build please try again later Invalid sort field for dataset dataset sort field An error code of 3 indicates an authentication error The error messages which can be returned are Invalid Username Password The address your computer is accessing this site from xxx xxx xxx xxx has been blocked due to excessive failed login attempts To have this block removed please contact contact email gt Alternatively the block will be automatically removed in two hours time An unknown login failure occurred The administrators have been notified of the event You do not have permission to use this service Missing authentication header in soap request
25. t value gt 5 lt value gt lt value gt 6 lt value gt lt attribute gt The between matchtype takes exactly two value elements and returns any results where the named attribute is between those two values including the values themselves So between 1 and 3 would include attributes with a value of 1 or 3 as well as attributes with a value of 2 Note that the number of parameters is not enforced by the web service but will accept any number of parameters greater than zero The web services will still behave consistently although the interpretation may not always be immediately obvious In general where a web service expects a single value if multiple values DK OneScotland accessing public services are supplied then the web service will return all results which match any of the values i e it is a logical or of the values So if the matchtype is equal to and the values supplied are 1 and 2 then the web service will return all records where the field either contains 1 or contains 2 2 4 3 Combined Searches A query element can contain multiple attribute elements In this case a data item must satisfy all conditions specified across all attributes The following query would therefore return all historical addresses in Stirling all matches where Town STIRLING and Logical_Status 8 lt ns query gt lt dataset gt ADDRESSES lt dataset gt gi IC 1e DUTEA lt name gt Town lt nam
26. te Type gt lt xsd sequence gt lt xsd element minOccurs 1 name name type xsd string gt lt xsd element minOccurs 1 maxOccurs unbounded name value type xsd string gt lt xsd sequence gt lt xsd attribute name matchtype type MatchType use optional gt xsd complexType xsd complexType name Within Type xsd sequence xsd element minOccurs 1 name easting type EastingType xsd element minOccurs 1 name northing type NorthingType xsd element minOccurs 1 name distance type xsd decimal lt xsd sequence gt xsd complexType lt xsd element name query gt lt xsd complexType gt lt xsd sequence gt lt xsd element minOccurs 1 name dataset type xsd string gt lt xsd element minOccurs 0 maxOccurs unbounded name attribute type Attribute Type xsd element minOccurs 0 maxOccurs 1 name area type xsd string lt xsd element minOccurs 0 maxOccurs 1 name within type Within Type xsd element minOccurs 0 maxOccurs 1 name sortField type xsd string lt xsd element minOccurs 0 maxOccurs 1 name sortOrder type SortOrderType lt xsd sequence gt lt xsd complexType gt lt xsd element gt lt xsd element name listdatasets gt lt xsd complexType gt lt xsd sequence gt lt xsd complexType gt lt xsd element gt lt xsd element name SearchResponseMessage gt lt xsd complexType gt lt xsd sequ
27. the OneScotland Gazetteer They are structured around datasets which contain fields which in turn contain the actual data This approach allows for flexibility making it easy for suitably authorised users to create new web services or modify existing ones This approach means that a single web service is provided to extract data and the caller specifies a dataset on which to operate So for example instead of calling one web service for an address search and a different web service for a UPRN search you Call the same web service for both but in the first case you specify the addresses dataset and in the second you specify the BLPUs dataset 2 Web Services 2 1 Overview There are two web services available sendNGListDataSetsMessage lists all available datasets whilst sendNGSearchMessage allows queries to be performed on those datasets So for example a dataset of BLPUs might contain fields such as UPRN Custodian code and last update date The first web service will let you know that such a dataset exists and which fields are available whilst the second web service lets you query that dataset for example identifying all BLPUs with a last update date of more than a year ago Before going on to discuss these web services in detail we first need to understand how to authenticate for those web services 2 2 Authentication In order to use the web service the user must supply their username and password the same one they use
28. to log in to the OSG web system This must be sent for every request and should be supplied in the SOAP header It consists of a HeaderLogin element which contains a username and a password element for example SoapEnv Header lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt If for some reason the authentication fails the SOAP response will contain an appropriate error message in the header section of the response data For example if either the username or password are invalid the following response would be sent lt SoapEnv Envelope xmlns SoapEnv xmlns ns Seele We lt SoapEnv Body gt DK OneScotland accessing public services Semis ListDataSetsResponseMessag xsi type nsl SearchResponseMessage NGSearchResponseData Header lt ResultCount gt 0 lt ResultCount gt lt ReturnCount gt 0 lt ReturnCount gt lt ErrorCode gt 3 lt ErrorCode gt lt ErrorMessage gt Invalid Username Password lt ErrorMessage gt lt Header gt lt Result gt lt Result gt lt NGSearchResponseData gt lt ns ListDataSetsResponseMessage gt SoapEnv Body lt SoapEnv Envelope gt 2 3 List Datasets sendNGListDataSetsMessage The first of the two available web services is simply to list the available
29. ts The results can be sorted by one of the fields in the dataset by adding a sortField element to the query for example to sort by last update date SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Header gt lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt lt ns query gt lt dataset gt BLPU lt dataset gt lt sortFPield Last Update Date sortField lt ns query gt lt SoapEnv Body SoapEnv Envelope By default this will return results sorted in ascending order in this example with earliest first To sort in descending order a sortOrder field can be added to the query and a value of desc can be supplied lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Header gt lt ns HeaderLogin gt lt username gt Alice lt username gt DK OneScotland accessing public services lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt lt ns query gt lt dataset gt BLPU lt dataset gt lt SOuEnilelid Laast Update Date sortField lt sortOrder gt desc lt sortOrder gt lt ns query gt lt SoapEnv Body gt SoapEnv Envelope The sortOrder field can also take a val
30. tsMessage lt soap operation soapAction http www scottishcitizen gov uk improvementservice nationali nfrastructure addresssearch sendNGSearchMessage gt lt input gt lt soap body use literal gt lt soap header message tns HeaderLoginMessage part HeaderLogin use literal gt lt input gt sSoutput soap body use literal lt output gt lt operation gt lt binding gt lt service name NGSearchService gt lt documentation gt National Gazetteer Search Web Service lt documentation gt port name NGSearchService binding tns SubmitMessageSoapHttp gt lt soap address location https devportal onescotlandgazetteer org uk webservice gt lt port gt lt service gt lt definitions gt 3 3 DK OneScotland accessing public services Response Codes and Messages The web service can return 4 possible error codes An error code of zero indicates a successful submission to the web service An error code of 1 indicates that there was an error with the XML sent to the web service This will return an error message such as Invalid XML Schema validation error error msg An error code of 2 indicates that the XML was syntactically correct but some other issue was encountered whilst processing the request for example requesting a dataset which does not exist The error messages which can be returned are Invalid dataset lt dataset gt Invalid attribute name for datase
31. ue of asc to return the results in ascending order which has the same effect as omitting the sortOrder field 2 4 6 Returning a Count of Matches Sometimes it is useful to be able to find out how many results match a request without actually returning the results themselves To provide such a feature the query tag in the request can take a type header attribute In this case the web service only returns the header part of the response and not the matches So for example if the following request was made SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Header gt lt ns HeaderLogin gt lt username gt Alice lt username gt lt password gt secret lt password gt lt ns HeaderLogin gt lt SoapEnv Header gt lt SoapEnv Body gt lt ns query type header gt lt dataset gt ADDRESSES lt dataset gt lt ns query gt lt SoapEnv Body gt SoapEnv Envelope The following might be returned lt SoapEnv Envelope xmlns SoapEnv xmlns ns gt lt SoapEnv Body gt lt ns SearchResponseMessage gt lt NGSearchResponseData gt lt Header gt lt ResultCount gt 2197410 lt ResultCount gt lt ReturnCount gt 250 lt ReturnCount gt lt ErrorCode gt 0 lt ErrorCode gt lt ErrorMessage gt Success lt ErrorMessage gt lt Header gt lt Result gt lt Result gt lt NGSearchResponseData gt lt
32. xLength 200 minLength 1 3 2 WSDL 3 2 1 WSDL URL The WSDL is available once access to the web services has been approved upon request from the OneScotland Gazetteer Custodian e https portal onescotlandgazetteer org uk webservice wsdl 3 2 2 WSDL Content The WSDL provided by the OneScotland Gazetteer Custodian should be consulted in preference to the version included in this document At the time of writing the WSDL is the following lt xml version 1 0 encoding UTF 8 gt lt definitions name NGSearchService targetNamespace http www scottishcitizen gov uk improvementservice nati onalinfrastructure addresssearch v0 1 xmlns http schemas xmlsoap org wsdl xmlns tns http www scottishcitizen gov uk improvementservice nationalin frastructure addresssearch v0 1 xmlns mime http schemas xmlsoap org wsdl mime xmlns http http schemas xmlsoap org wsdl http xmlns soapenc http schemas xmlsoap org soap encoding xmins xsd http www w3 org 2001 XMLSchema xmlns soap http schemas xmlsoap org wsdl soap types xsd schema targetNamespace http www scottishcitizen gov uk improvementservice nati onalinfrastructure addresssearch v0 1 elementFormDefault unqualified version 0 1 xmins http www scottishcitizen gov uk improvementservice nationalinfras tructure addresssearch v0 1 gt lt xsd element name HeaderLogin gt lt xsd complexType gt El all gt lt xsd element name username ty
Download Pdf Manuals
Related Search