EPSG and OGC URIs

The GeoRepository API at epsg.org can be used to obtain full CRS definitions in GML and WKT format, as well as print reports. Similar definitions can be obtained through the OGC Definition Server in GML. This page explains the similarities and differences.

Note that epsg.org should not be depended upon for "live" retrieval of individual CRS definitions at runtime (nor via the OGC Definition Server), but rather the definitions should be cached by the application. This to avoid resources being overloaded at EPSG, but also to ensure reliable implementation not relying on the API to be up at runtime. EPSG may block or throttle excessive requests from a party, or implement API keys in future. The recommended method to synchronize CRS definitions with the latest EPSG Dataset release is to use the Dataset Download option in SQL.

The OGC CRS Resolver and Definition Server

The Open Geospatial Consortium (OGC) Definitions Server uses a CRS (Coordinate Reference System) Resolver, specifically the SECORE (Semantic Coordinate Reference System Resolver), to resolve CRS URLs into full CRS definition.

OGC registered the opengis domain and the syntax of elements in a URI string such as "www.opengis.net/def/crs/EPSG/0/4326", following OGC document 06-023r1 (2006-08-08) "Definition identifier URNs in OGC namespace" and 09-046r6 (2018-05-17) "OGC Naming Authority - Procedures".

Some of the requests that go to the OGC Definition Server are redirected to the EPSG site. The EPSG API does not get any traffic from the OGC CRS Resolver, only from the Definition Server. The rules are:

1. Any URI request that has the root opengis.net goes follows normal internet protocols and goes to OGC.
2. Any request where the second element is /def goes to the OGC definitions server.
3. Any request where the third element is crs or coordinateOperation or datum or uom or … (there are about 20 CRS-related elements) then it is forwarded to the OGC resolver (hosted at Constructor University in Bremen) except when the 4th element (the authority) = EPSG and the 5th element (the version) = 0 when it is forwarded directly to the EPSG API via a string converter. (If the third element it is not one of these CRS-related elements then it is dealt with directly by the OGC definitions server). An URI request such as www.opengis.net/def/crs/EPSG/9.9/4326 will not come to EPSG, it will go to the OGC resolver (because the version ≠0).

What is an EPSG code?

Each item in the EPSG Dataset has an EPSG code. These are stable, unique, permanent identifiers for the EPSG Database content, in the range 1024-32677.

EPSG codes are unique within each of the 28 tables forming the relational table structure, but the same code value may be used in different tables. An exception is made for the two 'top level' objects, coordinate reference systems and coordinate operations (transformations and map projections), which share a single code range. For example, currently there are four EPSG items with code '1234':

1. One of these items with code 1234 is a transformation between WGS 84 and the Yacare coordinate reference system used historically in Uruguay.
   1. Because 1234 is used as the code for a transformation, there is no CRS with this code.
2. But 1234 is also the code for:
   1. an Extent (Tonga);
   2. a datum or reference frame (one of the SIRGAS-CON realizations for South America;
   3. and a scope or purpose (this one relevant to Australia).

Using EPSG codes to construct GeoRepository links

Links to directly fetch data from epsg.org can be constructed using EPSG codes following these examples:

1. GUI form:
   1. https://epsg.org/crs_4143/index.html (this is the simplified form of the link shown when using the GeoRepository interactively, replacing the name in https://epsg.org/crs_4143/Abidjan-1987.html with "index.html").
   2. https://epsg.org/transformation_1311/index.html (simplified from: https://epsg.org/transformation_1311/ED50-to-WGS-84-18.html). 
2. PDF report:   https://epsg.org/crs/print/id/4143 or https://epsg.org/transformation/print/id/1311
3. GML:  https://epsg.org/crs/gml/id/4143
4. WKT:  https://epsg.org/crs/wkt/id/4143

Using EPSG codes in the OGC http URI string

The Open Geospatial Consortium (OGC) created a standard syntax for a definition accessible through a URN string, which was soon superseded by a similar syntax for a resolvable http URI string

·         http://www.opengis.net/def/object_type/authority/version/identifier 

which can be used as for example:

·         http://www.opengis.net/def/coordinateOperation/EPSG/0/1234

·         http://www.opengis.net/def/crs/EPSG/0/nnnn 

or

·         http://www.opengis.net/def/area/EPSG/0/nnnn 

In the first of these examples, coordinateOperation is the object_type, EPSG is the authority (the code owner), 0 is the version element of the string (the EPSG Dataset version), and 1234 is the EPSG identifier (the EPSG code) of the coordinate operation. Because codes are never removed from the EPSG dataset, for EPSG code references the version element of the string is not needed and version 0 indicates the latest version of the Dataset. Omission of version from the string will invalidate the URI, unlike the earlier URN syntax.

As we saw earlier, there is (today) no EPSG CRS with code 1234. Hence, http://www.opengis.net/def/crs/EPSG/0/1234 returns an http 404 error.

But EPSG CRS code 2345 is defined, and http://www.opengis.net/def/crs/EPSG/0/2345 returns the definition of an EPSG CRS, in this case one for a part of China.

By default the information is returned as resolvable GML (geographic mark-up language). In this the components of the CRS may be found through a further call to the xlinks contained in the initial return.

The contained xlink https://epsg.org/api/v1/CoordRefSystem/4610/export?format=gml will return the baseGeodeticCRS for this Projected CRS, in this case EPSG CRS code 4610.

The links in this can in turn be followed (resolved) to give a full GML description of the initial CRS and its components.

For CRSs and coordinate transformations, by extending the OGC string with the suffix /wkt the definition may be returned encoded as Well-known Text (WKT) conformant with ISO 19162.

http://www.opengis.net/def/crs/EPSG/0/2345/wkt will return:

PROJCRS["Xian 1980 / Gauss-Kruger CM 117E",BASEGEOGCRS["Xian 1980",DATUM["Xian 1980",ELLIPSOID["IAG 1975",6378140,298.257,LENGTHUNIT["metre",1,ID["EPSG",9001]],ID["EPSG",7049]],ID["EPSG",6610]],ID["EPSG",4610]],CONVERSION["Gauss-Kruger CM 117E",METHOD["Transverse Mercator",ID["EPSG",9807]],PARAMETER["Latitude of natural origin",0,ANGLEUNIT["degree",0.0174532925199433,ID["EPSG",9102]],ID["EPSG",8801]],PARAMETER["Longitude of natural origin",117,ANGLEUNIT["degree",0.0174532925199433,ID["EPSG",9102]],ID["EPSG",8802]],PARAMETER["Scale factor at natural origin",1,SCALEUNIT["unity",1,ID["EPSG",9201]],ID["EPSG",8805]],PARAMETER["False easting",500000,LENGTHUNIT["metre",1,ID["EPSG",9001]],ID["EPSG",8806]],PARAMETER["False northing",0,LENGTHUNIT["metre",1,ID["EPSG",9001]],ID["EPSG",8807]],ID["EPSG",16320]],CS[Cartesian,2,ID["EPSG",4530]],AXIS["Northing (X)",north],AXIS["Easting (Y)",east],LENGTHUNIT["metre",1,ID["EPSG",9001]],ID["EPSG",2345]]

OGC URI gml example links

The following table shows examples of URIs for EPSG elements. When a code is passed to the EPSG API using the OGC URI it gets remapped to the correct export endpoint for the specific table (e.g., for coordinate operation 1041 and 1103 to a simple CT, for 9685 to a concatenated operation, and for 9375 to a PMO).