EPSG Dataset :: v12.003

3. Working with the API

The general structure of the API endpoints is such that there is a way to search a specific element type, retrieve a specific element using its code and export the element in two different formats depending on the element type, WKT and GML.

Example: Change request endpoints

*Figure 7 – Change request endpoint functions.*

The last of these three endpoints, /v1/Change, allows a user to search Change Requests using the following parameters:

keywords	Text or code is wanted. This is a text variable. However, if the string entered is all digits, it will search codes as numbers in addition to the text fields. Also, if a text string ends in 2 digits, such as NAD27, the search will expand and search for “NAD27” or “NAD 27”.
includeDeprecated	(Optional) Indicates whether the search should include elements that have been deprecated, i.e., are not valid. True/False. Set to True if deprecated entries should be included in the results.
sortField	Specify if the elements should be sorted in some way. Each type has a base set of fields that can be used, and additional parameters specific to the type.
page	To limit data transfer sizes, the next parameter pageSize allow the user to paginate the results and this parameter determines what page is returned.
pageSize	When the number of returned elements is high, the data transfer takes time and the required memory buffers are large. Setting a pageSize allows the user to limit the returned data amount with each call.

*Figure 8 – Optional parameters for the Change Request search.*

The call returns are documented and exposed by Swagger either as a model definition or example JSON. The model definition is seen in Appendix A. The JSON example is seen in Appendix B.

The first endpoint call, /v1/Change/{id}, allows the retrieval of a specific element in the Change table. The Key is the code, colloquially, EPSG code or authority code or Id. For change requests, this is a double value of the format year.index. As an example, 2021.1 is for the first Change Request issued in 2021, index uses 3 decimals and never ends with a 0. As can be seem in Figure 9, /v1/Change/{id} parameter is required.

*Figure 9 – Parameters needed for /v1/Change/{id}.*

Lastly, the endpoint /v1/Change/{id}/export is the export functionality. This allows a user to retrieve the definition of a specific element in either WKT, where supported, or GML, where supported. The /v1/Change/{id}/export parameters are as seen in Figure 10.

Table of Content

Wildcard	Example
% or *	Any wildcard characters
? or _	One wildcard character
[ - ]	[ - ] Range e.g. N[a-c] will return all geodetic objects that contains a string starting with the letter 'N' or 'n' followed by any of the letters contained within the range specified within the square bracket, e.g. letters a, b and c.
\|	Or e.g. E[a\|e]M will return all geodetic objects that contains a string starting with the letter E(e), ends with the letter M(m) and also contain either the letter a or letter e.