Geographic Query API
Resource Information
- URL
- https://b5m.gipuzkoa.eus/api/2.0/topoquery2
- Response Formats
- JSON, XML
- Authentication
- No
- Limited ratio
- No
Through this API you can query the toponymy and postal addresses of Gipuzkoa. You can access both alphanumeric data of geographic elements (names, postal addresses, surface data, etc.) and the vector geographic information of points, lines, and polygons (in GeoJSON format). The B5m 2.0 viewer uses this API to determine geographic locations and explore geographic elements. You can use the API in three ways:
1. View a b5m code on a map
You have obtained a b5m code through the Geographic Search API and want to locate that place on a map. To do this, you need to:
- We want to see the position and vector image of the b5m code D_A57413 (corresponding to the address Julio Caro Baroja 2 in San Sebastián, b5m headquarters)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?b5mcode=D_A57413&lang=en
2. What is this?
You want to know what it is a point in Gipuzkoa. Once you have the pair of coordinates of that point, you need to do the following:
- We have obtained a pair of geographic coordinates from Gipuzkoa (for example, by clicking on a map) and want to know what the clicked point is
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-2.008015,43.308970&z=16&lang=en
Keep in mind that the values of the z parameter (zoom level of the possible map) or scale (scale of the possible map) will influence the result (see the last table of this document for what is being searched in each case). If you want to search among all the elements of Gipuzkoa, do not use either of these two parameters (but be aware that the search may be very slow, as it will search through all georeferenced elements in the geographic database of Gipuzkoa).
3. What is here? (poi_pointsofinterest)
If you want to know what is in a certain area of Gipuzkoa (points of interest in administration, healthcare, culture, and tourism), you need to get the coordinates of the bounding box of that area, include the poi_pointsofinterest geographic element in the featuretypenames parameter, and do the following:
- We have obtained the coordinates of the bounding box of an area in Gipuzkoa (for example, by positioning ourselves on a map) and want to know what is in this area (points of interest)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-2.0256,43.308573,-1.99501,43.31381&featuretypenames=poi_pointsofinterest&z=18&lang=en
Request Parameters
| Parameter | Description | Default | Required |
|---|---|---|---|
| coors | Coordinates of the point or the bounding box to query (if it's a bounding box, define it this way). The maximum area of the bounding box is 100 km², if it is larger, this message will be shown. | - | Yes, if b5mcode is not provided |
| offset | Search radius (in metres), only taken into account when using the coors parameter. | 1 | No |
| b5mcode | b5m code, which can be obtained from the Geographic Search API; if provided, the coors parameter will not be considered. | - | No |
| srs | Spatial reference system (SRS expressed in the EPSG code). If not provided, the system will infer it. Compatible SRS include: EPSG:4326, EPSG:25830 and EPSG:3857. | System can infer it | No |
| querytype | Type of query: regular or whatishere. In the latter case, the query will return points of interest. | regular | No |
| z | Zoom level for the potential map. Values from 9 to 19 are accepted. This parameter affects the geographic objects being searched for, as shown in the table below | - | No |
| scale | Scale of the potential map. Values from 10000000 (scale 1:10,000,000) to 500 (scale 1:500) are accepted. This parameter affects the geographic objects being searched for, as shown in the table below | - | No |
| featuretypenames | List of element types to query (comma-separated); if not provided, all element types will be used. | all | No |
| featuretypes | Displays the list of element types if set to "true"; useful if we want to use the featuretypenames parameter. | false | No |
| downloadlist | Displays the list of available download types (cartography, LIDAR, orthophotos, etc.) if set to "true". | false | No |
| dwtypeid | Identifier of the download type. A number obtained from the downloadlist. | false | No |
| downloads | When querying by a geographic point (e.g. What is this? using the coors parameter), you can include download information related to that point (but note, this will make the response slower!). Depending on these conditions: if downloads=0, information will be provided without associated downloads (default option), if downloads=1, information will be provided with associated downloads, and if downloads=2, only download information will be provided (similar to the featuretypenames=dw_download). | 0 | No |
| geom | If set to "false", the geometry of the elements will not be shown. | true | No |
| lang | Language. Three options are supported: eu, es, en. | the one indicated by the browser | No |
| format | Specifies the response format. Should be: json, xml, or php. | json | No |
More examples
- 1. Query a coordinate or point (in the EPSG:4326 coordinate system), specifying longitude and latitude)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-2.008015,43.308970&lang=en
- 2. Query the previous point, but specify the zoom level (z=19, the results will be more precise)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-2.008015,43.308970&z=19&lang=en
- 3. Query a coordinate or point (in the EPSG:25830 coordinate system), using x and y coordinates)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=565019,4776036&lang=en
- 4. Query the previous point including the associated downloads (slower)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=565019,4776036&downloads=1&lang=en
- 5. Query a b5m code, in the EPSG:4326 coordinate system
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?b5mcode=M_010&srs=epsg:4326&lang=en
- 6. List the names of the available features (featuretypes) (Note: not all b5m features are available yet)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?featuretypes=true&lang=en
- 7. Query a point, specifying the feature to search within (m_municipalities)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-2.397771,43.036122&featuretypenames=m_municipalities&lang=en
- 8. Query a point, but only the downloads corresponding to that point (maps, orthophotos, LIDAR data, etc.) (dw_download)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-2.397771,43.036122&featuretypenames=dw_download&lang=en
- 9. Query a geographic window, and as in the previous example, only the downloads corresponding to that window (maps, orthophotos, LIDAR data, etc.) (dw_download)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-1.967,43.276,-1.939,43.287&featuretypenames=dw_download&lang=en
- 10. Display the list of download types
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?downloadlist=true&lang=en
- 11. Query a geographic window, but only one type of download in that window (dw_type_id=2, i.e., "Topographic Base") (parameters dw_download and dwtypeid)
-
https://b5m.gipuzkoa.eus/api/2.0/topoquery2?coors=-1.967,43.276,-1.939,43.287&featuretypenames=dw_download&dwtypeid=2&lang=en
(more examples will be added later)
Response
| Field | Description |
|---|---|
| info | Information about the API: licences, metadata, response time, messages, etc. |
| coors | The received coordinate request. |
| offset | Information about the search radius. |
| z | Zoom level used for the search. |
| crs | The spatial reference system used. |
| featuretypenames | List of features used for the query. |
| numberMatched | The number of features found. |
| features | Geographic matches found for a specific feature, in GeoJSON format. The data comes from a GetFeature request in an OGC WFS service; specifically from the gipuzkoa_wfs WFS service of b5m. |
| downloads | In the case of "What is this?" (second case), the list of downloads found in that location (orthophotos, base maps, BTA data, LIDAR data, etc.). |
| more_info | Similar to the previous case, but indicates whether more features have been found in the coordinate search (always referring to the zoom level in the request and whether the coordinates correspond to a point on the map). |
| external_links | If the search was based on a point, the response will include information on external links. |