SOAP API Test Tool (PDF download)
This document is the user description of the test tool for the SOAP API Platform to access the spatial data warehouse run by the Territorial Planning Department.
The SOAP API Platform test application is available at:
http://b5m.gipuzkoa.net/appws/publish.htm
Illustration 1 SOAP API Test Application Run Interface
The application is started up by clicking the Run button of the access interface (See Illustration 1 SOAP API Test Application Run Interface).
It is a client application implemented with Visual Studio 2005 and C# programming language.
2. Street Gazetteer search service
2.1 Description
The buscacallejero operation allows the user to perform different types of street gazetteer searches: streets door numbers, buildings, post codes, etc., according to the different input parameter options. The level of detail (service response information) changes according to the type of search performed.
The callejero (Street Gazetteer) search information interface is accessed from the "Callejero" application tab. See Illustration 2 Street Gazetteer Search Interface.
Illustration 2 Street Gazetteer Search Interface
The different "
"buttons execute the different searches that can be performed through this service. Click on the question mark button ("
")next to the search buttons, to establish which input parameter each one of the functions considers.The different search possibilities through this service are described below.
The complete list of the municipalities is displayed by clicking the button to the right of the "Código Municipio" Text Box and without putting any value in the text boxes. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 3 Municipality Search Interface.
A specific Municipality can be selected by entering the name in the "Municipio" Text Box or by entering the Code in the "Código Municipio" Text Box using the copy/paste option.
Click the button to the right of the "Código Municipio" Text Box to obtain the data relating to the Municipality in question. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 4 Specific Municipality Search Interface.
When you click the button to the right of the "Código Calle/Plaza" Text Box after entering a municipality, the list of streets in a municipality is displayed. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 5 Address Search Interface.
A specific Address can be selected by entering the name in the "Calle/Plaza" Text Box or by entering the Code in the "Código Calle/Plaza" Text Box using the copy/paste option.
Click the button to the right of the "Código Calle/Plaza" Text Box to obtain the data relating to the Address in question. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 6 Specific Address Search Interface.
The list of all the address numbers existing in a specific street is displayed by selecting a street and clicking the button to the "Númeror-Bis" Text Box. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 7 Street Number Search Interface.
A specific Street Number can be selected by entering the Number in the "Número" Text Box.
The list of the existing Buildings in a specific Street, if the street has been indicated; or in the whole municipality, if only the municipality has been indicated, is displayed by clicking the button to the right of the "Nombre de Edificio" Text Box. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 9 Building Name Search Interface.
A specific building can be selected by entering the name in the "Nombre de Edificio" Text Box.
The list of the existing Buildings in a specific Street, if it has been previously indicated; or in the whole municipality, if the street has not been indicated, is displayed by clicking the button to the right of the "Nombre de Edificio" Text Box. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 10 specific Building Name Search Interface.
All the Post Codes for a specific Municipality can be obtained by entering the Municipality Code or Name and clicking the button to the right of the "Código Postal" text box. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 11 Post Code Search Interface.
2.1.6 Search by Statistical District
All the Statistical Districts for a specific Municipality can be obtained by entering the Municipality Code or Name and clicking the button to the right of the Distrito text box. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 12 Statistical District Search Interface.
2.1.7 Search by Statistical Section
All the Statistical Sections for a specific municipality and district can be obtained by entering the Municipality Code or Name and the District Number.
Click the button to the right of the Distrito text box to obtain the different Sections in a District. The Question Mark button highlights the search filter fields in another colour and enables to perform searches using those fields. See Illustration 13 Statistical Section Search Interface.
2.1.8 Language
The possible language values throughout the application are:
3.1 Description
The service can be launched from the "BuscarToponimia" (Toponymy Search) application tab by entering values in the "Toponimo" Text Box and establishing the language code in the "Lengua" Text Box. Click the "Lanzar Servicio Toponimo" button to launch the service. See Illustration 14 Toponymy Search Interface.
Illustration 14 Toponymy Search Interface.
4.1 "Display Image" Operation
This function ("DibujarImagen") is used to obtain a map based on two coordinates that define the extension of the map (MBR). Additional information layers to be viewed can be specified. The available layers can be consulted using the "mapasdisponibles" operation (Get Maps) to establish which added layers can be viewed.
There are three pre-defined examples that show different layers (Datos 1, Datos 2 and Datos 3). The following image can be obtained by clicking Datos 2 and Launch DibujarImagen.
4.2 ""Available Maps" Operation (Layer Management) in the Display Image Service
This operation, known as setting (or category), displays a list of classes, groups and maps. The list of available maps can be activated using the "DibujarImagen" request.
As there is a hierarchy of the maps that orders the maps in "Groups" and the Groups in "Classes2, the group and class to which it belongs will have to be activated in order to activate a specific layer. See Illustration 16 Available Maps Interface.
5.1 Description
The Locate SOAP API contains different operations (or functions) that can be used to provide the geographical location of specific entities from the database, such as: municipalities, streets, urban centres, roads, kilometric points, toponymy, rivers, or just xy coordinates, to give just some examples.
Each one of the application tabs offers the possibility to locate specific entities with a common idiosyncrasy.
The returned information is the URL address of an image that includes the located item and can be viewed in the form. Specific alphanumerical information (attributes) of the located item is also returned: In some operations or functions, the image can be used to obtain geographical information (coordinates) of the searched item in specific standard formats (gml, wkb or wkt).
Additional information layers to be viewed can be specified. The available layers can be consulted using the "Maps" operation and the Dibujar Imagen Service (Display Image) to establish which added layers can be viewed.
5.2 Locate Street Gazetteer entities
Some standard identifiers available in the ID drop down menu can be selected or the search code entered leaving a space before the code in the Callejero (Street Gazetteer) tab under LocalizarObjetoPorId
N.B. For the integrators of the service´s consumer applications integrators, it is logically not necessary to add the space before the ID that is located, only in this interface of the test application.
The searchable entities in this case are: Regions, Municipalities, Urban Centres, Streets (Vector), Streets (Buildings), Statistical Districts and Sections, Buildings: ID, Muni_street_door, Business. Information about the business is obtained in order to locate the business identifiers. Information relating to the postal address, when applicable, is obtained for the other entities.
The request is executed using the "Lanzar Servicio" (Launch Service) button. See (Illustration 17 Example of Activities Location).
The searched entity or related entities are highlighted in the image that is obtained. For example:
* In Locate Street, the buildings whose postal address belongs to that street are highlighted
* In locate Districts and Services, all the buildings belonging to the district or section are highlighted
The URL field indicates the address where the image generated in the request is to be found.
Some standard identifiers available in the Id drop down menu can be selected or the search code entered leaving a space before the code in the Viales (Roadway) tab under LocalizarObjetoPorId.
N.B. For the integrators of the service´s consumer applications integrators, it is logically not necessary to add the space before the ID that is located, only in this interface of the test application.
The searchable entities in this case are: Roads/Train, Kilometric Points, Public Transport Lines and Public Transport Stop.
Under Location, an image can be obtained that contains the located entity, information about its attributes, and optionally an xml file in the gml, wkb or wkt format. The desired type of format can be selected in the drop down menu following on from the ID menu.
The image can be optionally requested under the "Image" drop down menu.
Other parameters that can be established under Locate are: Scale (only indicating the scale factor number), Language, setting and dimensions of the image to be obtained.
The request is executed using the "Lanzar Servicio" (Launch Service) button (See Illustration 18, Localization Example using a transport stop identifier).
The searched entity or related entities are highlighted in the image that is obtained. For example
* The Roadway is also highlighted in the kilometric point location.
* The public transport stops are highlighted under public transport line.
| Entity | Attributes |
|---|---|
| Roads/Train | Name, Identifier and description |
| Kilometric Points | Name, Identifier and description of the road to which it belongs. |
| Public Transport Line | Company, direction, route, type and the name set of the stops along the transport line. |
| Public Transport Stops | Public Transport Stops |
The gml, wkb or wkt xml files can be viewed when the Vector tab is activated (See Illustration 19 Example of viewing the gml file of the located entity) As the wkb file is a binary format and viewing it is therefore pointless, the number of vectors that it contains is indicated, which is proof that the wkb file has been correctly obtained in the service request.
The URL field indicates the address where the image generated in the request is to be found.
Illustration 18 Localization example using a transport stop identifier.
Illustration 19 Viewing example of the gml file of the located entity
Some standard identifiers available in the Id drop down menu can be selected or the search code entered leaving a space before the code in the Toponimia (Toponymy) tab under LocalizarObjetoPorId.
N.B. For the integrators of the service´s consumer applications integrators, it is logically not necessary to add the space before the ID that is located, only in this interface of the test application.
The searchable entities in this case are: Districts and Orography.
Under Location, an image can be obtained that contains the located entity, information about its attributes, and optionally an xml file in the gml, wkb or wkt format.
Other parameters that can be established under Locate are: Scale (only indicating the scale factor number), Language, setting and dimensions of the image to be obtained
The request is executed using the "Lanzar Servicio" button (See Illustration 20, Localization Example using a district identifier).
The searched entity or related entities are highlighted in the image that is obtained.
The attributes that are obtained according to the entity located are:
| Entity | Attributes |
|---|---|
| Neighbourhoods | Information on the neighbourhood and the municipality to which it belongs |
| Orography | Name, Identifier and description of the road to which it belongs. |
| Public Transport Line | Company, direction, route, type and the name set of the stops along the transport line. |
The URL field indicates the address where the image generated in the request is to be found.
Illustration 20 Localization example using a district identifier.
Some standard identifiers available in the ID drop down menu can be selected or the search code entered leaving a space before the code in the Ríos (Rivers) tab under LocalizarObjetoPorId.
N.B. For the integrators of the service´s consumer applications integrators, it is logically not necessary to add the space before the ID that is located, only in this interface of the test application.
The searchable entities in this case are: Rivers and Basins
Under Location, an image can be obtained that contains the located entity, information about its attributes, and optionally an xml file in the gml, wkb or wkt format.
Other parameters that can be established under Locate are: Scale (only indicating the scale factor number), Language, setting and dimensions of the image to be otained.
The request is executed using the "Lanzar Servicio" button (See Illustration 21, Basin localization example obtaining a wkt file with its coordinates).
Information about the name and identifier of the river and basin as applicable is obtained in the localization request.
The searched entity or related entities are highlighted in the image that is obtained.
The URL field indicates the address where the image generated in the request is to be found.
Illustration 21 Basin Localization Example obtaining the wkt file with its coordinates.
5.6 Locate map library entities
Some standard identifiers available in the Id drop down menu can be selected or the search code entered leaving a space before the code in the Toponimia (Toponymy) tab under LocalizarObjetoPorId.
N.B. For the integrators of the service´s consumer applications integrators, it is logically not necessary to add the space before the ID that is located, only in this interface of the test application.
The searchable entities in this case are: Districts and Orography.
Under Location, an image can be obtained that contains the located entity, information about its attributes, and optionally an xml file in the gml, wkb or wkt format.
Other parameters that can be established under Locate are: Scale (only indicating the scale factor number), Language, setting and dimensions of the image to be obtained
The request is executed using the "Lanzar Servicio" button (See Illustration 20, Localization Example using a district identifier).
The searched entity or related entities are highlighted in the image that is obtained.
The attributes that are obtained according to the entity located are:
Illustration 22 ID localization example of a map library item.
Some XY coordinate examples in any of the three systems in question can be selected in the XY tab, within LocalizarObjetoPorId. The coordinates and the benchmark coordinate system in question can also be introduced in the relevant Text Boxes: "Tipo" (Type), "Long" and "Lat".
An image can be obtained in localization where the located geographical point is in the centre and is highlighted with a red cross (See Illustration 23 XY coordinate localization example).
Other parameters that can be established under Locate are: Scale (only indicating the scale factor number), Language, setting and dimensions of the image to be obtained.
The request is executed using the "Lanzar Servicio" button.
The coordinates consulted in the other two benchmark systems are also obtained in the localization system.
The relevant zone is highlighted in the image that is obtained.
The URL field indicates the address where the image generated in the request is to be found.
Illustration 23 XY coordinate localization example.
6. ConsultarObjetoPorXY Service
6.1 Description
The ConsultarObjetoPorXY SOAP API contains different operations (or functions) that can be used to provide the geographical location of specific entities from the database, such as: physical environment, streets, roadways, rivers, or just xy coordinates, to give just some examples.
6.2 Consult Physical Environment Items
It is a function that returns information on the physical environment (Medio Físico) from a given geographical point, whose X and Y coordinates become the input parameters. There are some example values in the "Selección" drop down menu.
The relevant values are returned according to the topic that is indicated (See Illustration 24 Consult Item by Physical Environment Interface. "VEGETATION" search example in some specific coordinates).
Illustration 24 Consult Item by Physical Environment Interface. VEGETATION search example in some specific coordinates.
6.3 Consult Street Gazetteer Objects
It is a function that returns street gazetteer information from a given geographical point, whose X and Y coordinates become the input parameters. EDIFICIO (BUILDING) topic. There are some example values in the "Selección" drop down menu.
Illustration 25 Consult Street Gazetteer Object Interface. BUILDING search example.
It is a function that returns Roadway (Viales) information from a given geographical point, whose X and Y coordinates become the input parameters. There are some example values in the "Selección" drop down menu.
Illustration 25 Consult Roadway Object Interface
It is a function that returns river (Río) names from a given geographical point, whose X and Y coordinates become the input parameters. There are some example values in the "Selección" drop down menu.
Illustration 25 Consult River Item Interface.
It is a function that returns names of urban centres and districts from a given geographical point, whose X and Y coordinates become the input parameters. There are some example values in the "Selección" drop down menu.
Illustration 28 Consult Toponymy Item Interface.
This operation or function returns information from the point, whose X and Y coordinates become the input parameters. This information includes data such as Longitude and Latitude, the height of the point, etc. There are some example values in the "Selección" drop down menu.
Illustration 29 Search Item by XY Interface
6.8 Consult Items in the Map and Photo Library
This operation returns data from the map and photo library (Cartofototeca) on a specific geographical point, whose X and Y coordinates become the input parameters.
The types of maps that can be consulted are: Cartography, Cincomiles (1:5000) or Aerial Photos.
Illustration 29 Search Items in the Map Library
This operation provides data from relevant legislation, given a specific geographical point.
Illustration 31 Search Legislation Item Interface
7.1 Description
The Calculating Route (Calcular Ruta) SOAP API returns the coordinates of the polylines that make up a route when there it exists between the two or three points used as parameters. The route can be defined with the coordinates of an initial point, a final point and optionally, an intermediate point.
7.2 Consult Route Coordinates Operation
Given final X and Y coordinates, it returns the road route between two points. An intermediary point may optionally be specified.
The function returns an XML codified in a String with the XY values of the route line and vertices.
In the application tab, there are two example values in the drop down menu Selection that can be selected and tested by clicking the Launch Service button.
The interface displays the coordinates of the polylines of the route returned by the service (See Illustration 32 Example of route consultation between two points).
Illustration 32 Example of route consultation between two points.
