Skip to Content
Version 4.1 by Artur on 2025/07/14 10:19
Show last authors
1 {{box title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] recognizes that statistics refers to units or facts sited in places or areas that may be referenced to geodesic coordinates. This section presents the technical specifications to "geo-reference" those objects and facts in [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]], by establishing ways to make relations to geographic features over the Earth using a defined coordinates system.
6
7 [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] can support three different ways for referencing geospatial data:
8
9 1. __Indirect Reference to Geospatial Information.__ Including a link to an external file containing the geospatial information. This is the only backwards compatible approach. Since this [[representation>>doc:sdmx:Glossary.Representation.WebHome]] of geospatial information is not included inside the data message, the main use case would be connecting dissemination systems for making use of external tools, like GIS software.
10 1. __Geographic Coordinates.__ Including the coordinates of a specific geospatial feature as a set of coordinates. This is suitable for any statistical information that needs to be georeferenced especially for the exchange of microdata.
11 1. __A Geographic Codelist.__ Includes a type of Codelist, listing predefined geographies that are represented by geospatial information. These geographies could be administrative (including administrative boundaries or enumeration areas), lines, points, or gridded geographies. Regardless, the geospatial information used to represent the geography would contain both [[dimensions>>doc:sdmx:Glossary.Dimension.WebHome]] and/or [[attributes>>doc:sdmx:Glossary.Attribute.WebHome]]; therefore, representing an advantage for the data modellers as it provides a clear way to identify those [[dimensions>>doc:sdmx:Glossary.Dimension.WebHome]] developing a "Geospatial" role.
12
13 == 7.1 Indirect Reference to Geospatial Information ==
14
15 This option provides a way to include external references to geospatial information through a file containing it. The external content may be geographical or thematic maps with different levels of precision. All the processing of geospatial data is made through external applications that can interpret the information in different formats.
16
17 The reference to the external files containing geospatial information is made using some recommended [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] [[Attributes>>doc:sdmx:Glossary.Attribute.WebHome]], with the following content:
18
19 * **GEO_INFO_TEXT**. A description of the kind of information being referenced.
20 * **GEO_INFO_URL**. A URL which points to the resource containing the referred geospatial information. The resource might be a file with static geodesic information or a web service providing dynamic construction of geometries.
21 * **GEO_INFO_TYPE**. Coded information describing a standard format of the file that contains the geospatial information. The format types are taken from the list of Format descriptions for Geospatial Data managed by the US Library of the Congress ([[https:~~/~~/www.loc.gov/preservation/digital/formats/fdd/gis_fdd.shtml>>https://https:www.loc.govpreservationdigitalformatsfddgis_fdd.shtml]]). Allowed types in [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] are listed in the **Geographical Formats** [[code list>>doc:sdmx:Glossary.Code list.WebHome]] (**CL_GEO_FORMATS**). Examples of the [[codes>>doc:sdmx:Glossary.Code.WebHome]] contained in the document are:
22
23 (% style="width:543.294px" %)
24 |(% style="width:200px" %)(((
25 * Code
26 )))|(% style="width:340px" %)(((
27 * Description
28 )))
29 |(% style="width:200px" %)(((
30 * **GML**
31 )))|(% style="width:340px" %)(((
32 * Geography Markup Language
33 )))
34 |(% style="width:200px" %)(((
35 * **GeoTIFF**
36 )))|(% style="width:340px" %)(((
37 * GeoTIFF
38 )))
39 |(% style="width:200px" %)(((
40 * **KML_2_2**
41 )))|(% style="width:340px" %)(((
42 * KML Version 2.2
43 )))
44 |(% style="width:200px" %)(((
45 * **GEOJSON_1_1**
46 )))|(% style="width:340px" %)(((
47 * GeoJSON Version 1.1
48 )))
49
50 Depending on the intended use, these [[attributes>>doc:sdmx:Glossary.Attribute.WebHome]] may be attached at the [[dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] level, the series level or the observation level.
51
52 The indirect reference to geospatial information in [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] is recommended to be used for dissemination purposes, where the statistical information is complemented by geographical [[representations>>doc:sdmx:Glossary.Representation.WebHome]] of places or regions.
53
54 == 7.2 Geographic Coordinates ==
55
56 This option to represent geospatial information in [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] provides an efficient way for including geographic information with different levels of granularity, due to its flexibility. Geospatial information is represented using the GeospatialInformation type, as defined in the data types of the [[SDMX Information Model>>doc:sdmx:Glossary.SDMX Information Model.WebHome]]. A "GEO_FEATURE_SET" role should be assigned to any [[Component>>doc:sdmx:Glossary.Component.WebHome]] of this type.
57
58 The GeospatialInformation data type can be assigned to a [[Dimension>>doc:sdmx:Glossary.Dimension.WebHome]], DataAttribute, MetadataAttribute or a [[Measure>>doc:sdmx:Glossary.Measure.WebHome]] with the "GEO_FEATURE_SET" role assigned; it can be included in a [[dataset>>doc:sdmx:Glossary.Data set.WebHome]] or metadataset.
59
60 Any [[Component>>doc:sdmx:Glossary.Component.WebHome]] used for representing a Geographical Feature Set, i.e., used to describe geographical characteristics, must have a “GEO_FEATURE_SET” role. Its [[Representation>>doc:sdmx:Glossary.Representation.WebHome]] would be of textType="GeospatialInformation". The GeospatialInformation type is not intended to replace standard geospatial information formats, but instead provide a simple way to describe precise geographical characteristics in [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] [[data sets>>doc:sdmx:Glossary.Data set.WebHome]] agnostic of any particular geospatial software product or use case.
61
62 The GeospatialInformation type should be used to describe geographical features like points (e.g., locations of places, landmarks, buildings, etc.), lines (e.g., rivers, roads, streets, etc.), or areas (e.g., geographical regions, countries, islands, land lots, etc.). A mix of different features is possible too, e.g., combining polygons and geographical points to describe a country and the location of its capital.
63
64 The [[components>>doc:sdmx:Glossary.Component.WebHome]] that conform to the structure of the GeospatialInformation type are:
65
66 * X_COORDINATE: The horizontal (longitude) value of a pair of coordinates expressed in the Coordinate Reference System (CRS), mandatory.
67 * Y_COORDINATE**:** The vertical value (latitude) of a pair of coordinates expressed in the CRS units, mandatory.
68 * ALT: The height (altitude) from the reference surface is expressed in meters, optional.
69 * CRS: The [[code>>doc:sdmx:Glossary.Code.WebHome]] of the Coordinate Reference System is used to reference the coordinates in the flow, optional.
70
71 The [[code>>doc:sdmx:Glossary.Code.WebHome]] of the CRS will be as it appears in the EPSG Geodetic Parameter Registry ([[http:~~/~~/www.epsg-registry.org/>>https://http:www.epsg-registry.org]]) maintained by the International Association of Oil and Gas Producers. If this element is omitted, by default, the CRS will be the World Geodetic System 1984 (WGS 84, EPSG:4326).
72
73 * PRECISION: Precision of the coordinates, expressing the possible deviation in meters from the exact geodesic point, optional.
74
75 This [[component>>doc:sdmx:Glossary.Component.WebHome]] is only allowed if the CRS is specified too. If omitted, it will be interpreted as limited it to the expected measurement [[accuracy>>doc:sdmx:Glossary.Accuracy.WebHome]] (e. g. a standard GPS has an [[accuracy>>doc:sdmx:Glossary.Accuracy.WebHome]] of 10m).
76
77 * GEO_DESCRIPTION: Text for additional information about the place, geographical feature, or set of geographical features, optional.
78
79 Geographical features (GEO_FEATURES) are collections of geographical features intended to be used to represent geographical areas like countries, regions, etc., or objects, like water bodies (e. g. rivers, lakes, oceans, etc.), roads (streets, highways, etc.), hospitals, schools, and the like. They are represented in the following way:
80
81 **GEO_FEATURE, GEO_FEATURE): GEO_DESCRIPTION**
82
83 * GEO_FEATURE represents a set of points defining a feature following the ISO/IEC 13249-3:2016 standard to conform Well-known Text (WKT) for the [[representation>>doc:sdmx:Glossary.Representation.WebHome]] of geometries in a format defined in the following way:
84
85 **GEOMETY_TYPE (GEOMETRY_REP)**
86
87 * GEOMETRY_TYPE: A string with a closed vocabulary defining the type of the geometry that represents a geographical [[component>>doc:sdmx:Glossary.Component.WebHome]] of the GEO_FEATURES collection, mandatory.
88
89 Three types are allowed:
90
91 1. **Point**, a specific geodesic point, like the centroid of a city or a hospital. It is represented with the string “POINT”
92 1. **Line**, a feature defining a line like a road, a river, or similar. It is represented with the string  “LINESTRING”
93 1. **Area**, a polygon defining a closed area. It is represented with the string “POLYGON”
94
95 If the GEOMETRY_REP is going to be including the height (ALT) [[component>>doc:sdmx:Glossary.Component.WebHome]], a “Z” must be added after the string qualifying the GEOMETRY_TYPE. In this way, we will have: “POINT Z”, “LINESTRING Z” and “POLYGON Z”
96
97 Other feature types (e.g. Triangular irregular networks, “TIN”) are not supported yet directly, except grids that are detailed in 7.3.
98
99 * GEOMETRY_REP: [[Representation>>doc:sdmx:Glossary.Representation.WebHome]] of each of the types The way to represent each GEO_FEATURE_TYPE will be:
100 ** A point (POINT): “COORDINATES”
101 ** A line (LINESTRING): “COORDINATES, COORDINATES, …”
102 ** An area (POLYGON): “(COORDINATES, COORDINATES, …),
103
104 (COORDINATES, COORDINATES, …)”
105
106 Where: 
107
108 * COORDINATES: Represents an individual set of coordinates composed by the  X_COORDINATE (X), Y_COORDINATE (Y), and ALT (Z) in the following way “X Y Z” or “X Y” defining a single point of the polygon. Altitude is to be reported in meters.
109
110 In an expanded way, GEO_FEATURE may be represented in the following ways:
111
112 **POINT (X_COORDINATE Y_COORDINATE): GEO_DESCRIPTION**
113 **POINT Z (X_COORDINATE Y_COORDINATE ALT): GEO_DESCRIPTION**
114 **LINESTRING (X_COORDINATE Y_COORDINATE, X_COORDINATE**
115 **Y_COORDINATE, …): GEO_DESCRIPTION**
116 **LINESTRING Z (X_COORDINATE Y_COORDINATE ALT, X_COORDINATE**
117 **Y_COORDINATE ALT, …): GEO_DESCRIPTION**
118 **POLYGON  ((X_COORDINATE Y_COORDINATE, X_COORDINATE**
119 **Y_COORDINATE, …), (X_COORDINATE Y_COORDINATE, X_COORDINATE**
120 **Y_COORDINATE, …), …): GEO_DESCRIPTION**
121 **POLYGON Z ((X_COORDINATE Y_COORDINATE ALT, X_COORDINATE**
122 **Y_COORDINATE ALT, …), (X_COORDINATE Y_COORDINATE ALT,**
123 **X_COORDINATE Y_COORDINATE ALT, …), …): GEO_DESCRIPTION**
124
125 An example of how GEO_FEATURES may be represented in an expanded way would be:
126
127 **(POLYGON Z ((X_COORDINATE Y_COORDINATE ALT, X_COORDINATE**
128 **Y_COORDINATE ALT, …), (X_COORDINATE Y_COORDINATE ALT,**
129 **X_COORDINATE Y_COORDINATE ALT, …), …), POLYGON Z**
130 **((X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE**
131 **ALT, …), (X_COORDINATE Y_COORDINATE ALT, X_COORDINATE**
132 **Y_COORDINATE ALT, …), …), POLYGON Z ((X_COORDINATE**
133 **Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …),**
134 **(X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …), …), …): GEO_DESCRIPTION**
135
136 Accordingly to this logic, an example of an expanded expression representing a value of the GeospatialInformation may be the following:
137
138 **“CRS, PRECISION: {(POLYGON Z ((X_COORDINATE Y_COORDINATE ALT,**
139 **X_COORDINATE Y_COORDINATE ALT, …), (X_COORDINATE Y_COORDINATE**
140 **ALT, X_COORDINATE Y_COORDINATE ALT, …), …), POLYGON Z**
141 **((X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE**
142 **ALT, …), (X_COORDINATE Y_COORDINATE ALT, X_COORDINATE**
143 **Y_COORDINATE ALT, …), …), POLYGON Z ((X_COORDINATE**
144 **Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …),**
145 **(X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT,**
146 **…), …), …): GEO _DESCRIPTION}, {(POLYGON Z ((X_COORDINATE**
147 **Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …),**
148 **(X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …), …), POLYGON Z ((X_COORDINATE Y_COORDINATE ALT,**
149 **X_COORDINATE Y_COORDINATE ALT, …), (X_COORDINATE Y_COORDINATE**
150 **ALT, X_COORDINATE Y_COORDINATE ALT, …), …), POLYGON Z**
151 **((X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …), (X_COORDINATE Y_COORDINATE ALT, X_COORDINATE Y_COORDINATE ALT, …), …), …): GEO _DESCRIPTION}, …:**
152 **GEO_DESCRIPTION”**
153
154 Validation rules must be added to the XML Schema to ensure the integrity of the specification according to the proposed syntax.
155
156 == 7.3 A Geographic Codelist ==
157
158 Geography is represented by geospatial information. Within [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]], geospatial information is conceptually represented by the "GEO_FEATURE_SET" role/specification. This approach uses a specialized form of [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] Codelist, named "GeoCodelist", which is a Codelist containing the Geography used to demarcate the geographic extent. This is implemented in two ways:
159
160 1. Geographic. It is a regular codelist that has been extended to add a geographical feature set to each of its items, typically, this would include all types of administrative geographies;
161 1. Grid. As a codelist that has defined a geographical grid composed of cells representing regular squared portions of the Earth.
162
163 A GeoCodelist is a Codelist as defined in the [[SDMX Information Model>>doc:sdmx:Glossary.SDMX Information Model.WebHome]] that has the GeoType property added. GeoType can take one of two values "Geographic" or "GeoGrid".
164
165 "Geographic" corresponds to the first way to implement a GeoCodelist. When the GeoCodelist includes a GeoType="Geographic"// //property, a GeoFeatureSet property is added to each of the items in the [[code list>>doc:sdmx:Glossary.Code list.WebHome]] to implement a Geographic GeoCodelist.
166
167 On the other hand, when GeoType="GeoGrid"// //it is defining a gridded GeoCodelist, and it is necessary to add a grid definition to the Codelist identifier using the gridDefinition property. The [[components>>doc:sdmx:Glossary.Component.WebHome]] needed to define a geographical grid are the following:
168
169 * CRS: The [[code>>doc:sdmx:Glossary.Code.WebHome]] of the Coordinate Reference System is used to reference the coordinates in the flow, optional. The [[code>>doc:sdmx:Glossary.Code.WebHome]] of the CRS will be as it appears in the EPSG Geodetic Parameter Registry ([[http:~~/~~/www.epsg>>url:http://www.epsg-registry.org/]][[->>url:http://www.epsg-registry.org/]][[registry.org/>>url:http://www.epsg-registry.org/]][[)>>url:http://www.epsg-registry.org/]] maintained by the International Association of Oil and Gas Producers. If this [[component>>doc:sdmx:Glossary.Component.WebHome]] is omitted, by default the CRS will be the World Geodetic System 1984 (WGS 84, EPSG:4326).
170 * REFERENCE_CORNER: A [[code>>doc:sdmx:Glossary.Code.WebHome]] composed of two characters to define the position of the coordinates that will be used as a starting reference to locate the cells. The possible values of this [[code>>doc:sdmx:Glossary.Code.WebHome]] can be** **UL (Upper Left), UR (Upper Right), LL (Lower Left), or LR (Lower Right). If this [[component>>doc:sdmx:Glossary.Component.WebHome]] is omitted the value LL (Lower Left) will be taken by default. This element is optional.
171 * REFERENCE_COORDINATES: Represents the starting point to reference the cells of the grid, accordingly to the CRS and the REFERENCE_CORNER. It is represented by an individual set of coordinates composed by the X_COORDINATE (X) and Y_COORDINATE (Y) in the following way "X,Y". This element is mandatory if GEO_STD is omitted.
172 * CELL_WIDTH: The size in meters of a horizontal side of the cells in the grid. This element is mandatory if GEO_STD is omitted.
173 * CELL_HEIGHT: The size in meters of a vertical side of the cells in the grid. This element is mandatory if GEO_STD is omitted .
174 * GEO_STD: A restricted text value expressing that the cells in the grid will provide information about matching [[codes>>doc:sdmx:Glossary.Code.WebHome]] existing in another reference system that establishes a mechanism to define the grid. This element is optional.
175
176 Accepted values for this [[component>>doc:sdmx:Glossary.Component.WebHome]] are included in the Geographical Grids Codelist (CL_GEO_GRIDS). Examples contained in the mentioned document are:
177
178 (% style="width:682.294px" %)
179 |(% style="width:196px" %)**Value**|(% style="width:483px" %)**Description**
180 |(% style="width:196px" %)GEOHASH|(% style="width:483px" %)GeoHash
181 |(% style="width:196px" %)GEOREF|(% style="width:483px" %)World Geographic Reference System
182 |(% style="width:196px" %)MGRS|(% style="width:483px" %)Military Grid Reference System
183 |(% style="width:196px" %)OLC|(% style="width:483px" %)Open Location [[Code>>doc:sdmx:Glossary.Code.WebHome]] / Plus [[Code>>doc:sdmx:Glossary.Code.WebHome]]
184 |(% style="width:196px" %)QTH|(% style="width:483px" %)Maidenhead Locator System /QTH Locator / IAURU Locator
185 |(% style="width:196px" %)W3W|(% style="width:483px" %)What3words™
186 |(% style="width:196px" %)WOEID|(% style="width:483px" %)Where On Earth Identifier
187
188 The GRID_DEFINITION element will contain a regular expression string corresponding to the following format:
189
190 "**CRS: REFERENCE_CORNER; REFERENCE_COORDINATES; CELL_WIDTH, CELL_HEIGHT: GEO_STD**"
191
192 In an expanded way we would have:
193
194 "**CRS:REFERENCE_CORNER; X_COORDINATE, Y_COORDINATE; CELL_WIDTH, CELL_HEIGHT: GEO_STD**"
195
196 If the grid will be fully adhering to a standard declared in the GEO_STD, the definition of each [[code>>doc:sdmx:Glossary.Code.WebHome]] in the [[code list>>doc:sdmx:Glossary.Code list.WebHome]] will be optional. In other case, each item in the [[code list>>doc:sdmx:Glossary.Code list.WebHome]] must be assigned to one cell in the grid, which is made by adding the GEO_CELL element to each item of the [[code list>>doc:sdmx:Glossary.Code list.WebHome]] that will contain a regular expression string composed of the following [[components>>doc:sdmx:Glossary.Component.WebHome]]:
197
198 * GEO_COL**: **The number of the column in the grid starting by zero.
199 * GEO_ROW**: **The number of the row in the grid starting by zero.
200 * GEO_TAG**: **An optional text to include additional information to the cell.
201 * GEO_CELL will have values with the following format: "**GEO_COL, GEO_ROW: GEO_TAG**"
202
203 When using a gridded GeoCodelist we may use the GEO_TAG to integrate the cells in the grid to the [[codes>>doc:sdmx:Glossary.Code.WebHome]] used by other standard defined grids. As an example, GEO_TAG can take the values of the Open Location [[Codes>>doc:sdmx:Glossary.Code.WebHome]], GeoHash, etc. If this is done, the GEO_STD [[component>>doc:sdmx:Glossary.Component.WebHome]] must have been added to the definition of the grid. If the GEO_STD is omitted, the GEO_TAG contents will be taken just as free text.