(Quick Reference)

2 Web Service API - Reference Documentation

Authors: John Cartwright, John LaRocque, Evan McQuinn, Rob Prentice, Ken Tanaka, Lisa Taylor, Tess Thyer, Kris Woyna

Version: 1.1.1

2 Web Service API

The Gazetteer exposes a REST-style API to facilitate integration with other software. Please contact ngdc.gazetteer@noaa.gov with any questions or comments that arise regarding use of this interface.

2.1 Feature

A Feature represents a physical undersea feature which has potentially number of attributes associated with it.

Retrieving a Specified Undersea Feature

A individual feature can be retrieved with a GET request using this URL pattern:

http://www.ngdc.noaa.gov/gazetteer/rest/feature/<feature-id>

This pattern ends with the string "rest/feature/", followed by '<feature-id>', which represents the numeric identifier associated with a particular undersea feature.

Example:

http://localhost:8080/gazetteer/rest/feature/101

{
    "id": 101, 
    "name": "Abbott", 
    "type": {
        "id": 67, 
        "name": "Seamount", 
        "description": "A discrete (or group of) large isolated elevation(s), greater
		  than 1,000 m in relief above the sea floor, characteristically of conical form.
		  See also GUYOT.", 
        "lastUpdated": "2013-04-09"
    },
    "featureId": 1, 
    "status": "APPROVED", 
    "geometry": "POINT (174.3 31.8)", 
    "secondaryGeometry": null, 
    "proposer": null, 
    "proposalYear": null, 
    "discoverer": null, 
    "discoveryYear": null, 
    "meeting": null, 
    "lastUpdated": "2013-04-09", 
    "history": null, 
    "comments": null, 
    "minDepth": null, 
    "maxDepth": null, 
    "totalRelief": null, 
    "dimension": null
}

Retrieving a List of Undersea Features

A collection of undersea features matching specified criteria can be retrieved with a GET request using the URL pattern shown below. This request returns a list of features that includes all attributes that have been defined for each feature, including their names.

http://www.ngdc.noaa.gov/gazetteer/rest/feature<param-list>

This pattern ends with the string "rest/feature", followed by a parameter list of the form: "?name1=value&name=value...". Parameters are added to the request in order to specify the criteria that distinguish undersea features of interest. If no parameters are specified, then all features are returned. The following parameters are supported:

ParameterDescriptionExample
namethe specific term for a feature. Case-insensitive, matches from beginning of namename=ab
featureTypethe generic term for a feature. Case-insensitivefeatureType=seamount
aoiarea of interest, expressed a well-known text polygonaoi=POLYGON((0 0, 180 0, 180 90, 0 90, 0 0))
lastModifiedDate on which a feature was last updated, format = YYYY-MM-DDlastUpdated=YYYY-MM-DD
meetingMost recent SCUFN meeting at which action was taken regarding this featuremeeting=SCUFN24
discoverDiscoverer of this feature. matches text anywhere in fielddiscover=taylor
proposerProposer of this feature. matches text anywhere in field.discover=taylor
maxmaximum number of features to returnmax=1000

Example:

http://www.ngdc.noaa.gov/gazetteer/rest/feature?name=ab&featureType=Seamount&max=10000

{
"totalCount":1,
"items":[
  {
    "id": 101,
    "name": "Abbott",
    "type": {
        "id": 67,
        "name": "Seamount",
        "description": "A discrete (or group of) large isolated elevation(s), greater
		  than 1,000 m in relief above the sea floor, characteristically of conical
		  form. See also GUYOT.",
        "lastUpdated": "2013-04-09"
    },
    "featureId": 1,
    "status": "APPROVED",
    "geometry": "POINT (174.3 31.8)",
    "secondaryGeometry": null,
    "proposer": null,
    "proposalYear": null,
    "discoverer": null,
    "discoveryYear": null,
    "meeting": null,
    "lastUpdated": "2013-04-09",
    "history": null,
    "comments": null,
    "minDepth": null,
    "maxDepth": null,
    "totalRelief": null,
    "dimension": null
  }
]
}

Retrieving a List of Undersea Feature Names

A list of the names of undersea features matching specified criteria can be retrieved using a GET request and the URL pattern shown below. This request reurns a list of feature names only.

http://www.ngdc.noaa.gov/gazetteer/rest/feature/name<param-list>

This pattern ends with the string "rest/feature/name", followed by a parameter list. of the form: "?name1=value&name=value...". Parameters are added to the request in order to specify the criteria that distinguish undersea features of interest. As shown below, the same parameters that can be used to select a feature for display are available here for selecting features to be retrieved.

ParameterDescriptionExample
namethe specific term for a feature. Case-insensitive, matches from beginning of namename=ab
featureTypethe generic term for a feature. Case-insensitivefeatureType=seamount
aoiarea of interest, expressed a well-known text polygonaoi=POLYGON((0 0, 180 0, 180 90, 0 90, 0 0))
lastModifiedDate on which a feature was last updated, format = YYYY-MM-DDlastUpdated=YYYY-MM-DD
meetingMost recent SCUFN meeting at which action was taken regarding this featuremeeting=SCUFN24
discoverDiscoverer of this feature. matches text anywhere in fielddiscover=taylor
proposerProposer of this feature. matches text anywhere in field.discover=taylor
maxmaximum number of features to returnmax=1000

Example:

http://www.ngdc.noaa.gov/gazetteer/rest/feature/name?name=ab&featureType=seamount

{
"totalCount":1,
"items":[
  {
  "id":101,
  "name":"Abbott Seamount"
  }
]
}

Exporting a List of Undersea Features

A collection of undersea features may be exported using a GET request and this URL pattern:

http://www.ngdc.noaa.gov/gazetteer/rest/feature/export<param-list>

This pattern ends with the string "rest/feature/export", followed by a parameter list of the form: "?name1=value&name=value...". Parameters are added to the request in order to specify the criteria that distinguish undersea features of interest. As shown below, the same parameters that can be used to select a feature for display are available here for selecting features to be exported. In addition, a 'format' parameter is available for specifying the desired file format for the export.

ParameterDescriptionExample
namethe specific term for a feature. Case-insensitive, matches from beginning of namename=ab
featureTypethe generic term for a feature. Case-insensitivefeatureType=seamount
aoiarea of interest, expressed a well-known text polygonaoi=POLYGON((0 0, 180 0, 180 90, 0 90, 0 0))
lastModifiedDate on which a feature was last updated, format = YYYY-MM-DDlastUpdated=YYYY-MM-DD
meetingMost recent SCUFN meeting at which action was taken regarding this featuremeeting=SCUFN24
discoverDiscoverer of this feature. matches text anywhere in fielddiscover=taylor
proposerProposer of this feature. matches text anywhere in field.discover=taylor
maxmaximum number of features to returnmax=1000
formatthe format in which to deliver the output. Options include excel, text, shapefileformat=excel

Example:

http://www.ngdc.noaa.gov/gazetteer/rest/feature/name?name=ab&featureType=seamount&format=shapefile

2.2 FeatureType

An undersea feature type is a generic term that classifies undersea features according to their general characteristics. In the name "Abbott Seamount", for example, "Seamount" is the feature type. Other examples of feature types are "Sea Channel", "Trough", and "Shelf".

Acquiring a List of Feature Types

To retrieve a list of undersea feature types, use a GET request with one of the following URL patterns:

http://www.ngdc.noaa.gov/gazetteer/rest/featuretype
http://www.ngdc.noaa.gov/gazetteer/rest/featuretype<param-list>

This pattern ends with the string "rest/featuretype", followed by an optional parameter list of the form: "?name1=value&name=value...". If specified without parameters, then all types are returned. With parameters, a portion of the list, starting at the specified offset and limited to a specified maximum number of elements, is returned. The following parameters are supported:

ParameterDescriptionExample
maxmaximum number of feature types to returnmax=1000
offsetstarting index for the requested sampleoffset=10

Example

http://www.ngdc.noaa.gov/gazetteer/rest/featuretype?max=2&offset=35

Returns

{
  "items":[
  {
    "id":267,
    "name":"Mud Volcanoes",
    "description":"Mounds or cone-shaped features formed by expulsion of
	  non-magmatic liquids and gasses.",
    "lastUpdated":"2013-04-05"
  },
  {
    "id":257,
    "name":"Pass",
    "description":null,
    "lastUpdated":"2013-04-05"
  }],
  "totalCount":70
}

2.3 Map Service

Accessing the undersea features as a layer in ArcMap.

The undersea features displayed by Gazetteer can be displayed as a standalone GIS layer in ArcMap by clicking the URL below. Use of this request returns a map file as an attachment that can be saved locally. If this request were invoked directly from a browser, for example, then the browser would generate a dialog allowing you to save the file. This allows clients to integrate undersea features into their own cartographic maps or spatial analysis.

http://maps.ngdc.noaa.gov/arcgis/rest/services/web_mercator/undersea_features/MapServer?f=lyr&v=9.3

Accessing the undersea features as an OGC WMS layer.

The undersea features displayed by Gazetteer can be accessed by clients (like OpenLayers) that support the Open Geospatial Consortium's (OGC) Web Mapping Service (WMS) Specification using the URL below. Use of this request returns a map file as an attachment that can be saved locally. If this request were invoked directly from a browser, for example, then the browser would generate a dialog allowing you to save the file.

http://maps.ngdc.noaa.gov/arcgis/services/web_mercator/undersea_features/MapServer/WMSServer?request=GetCapabilities&service=WMS&version=1.3

Accessing the undersea features as KML.

KML stands for Keyhole Markup Language, named after the company that originally developed the language. It is a markup language similar to XML and HTML that Google supports to hold web content. KMZ stands for KML-Zipped. It is the default format for KML because it is a compressed version of the file. One of the more powerful features of KMZ is that it allows any images you use – say custom icons, or images in your descriptions – to be zipped up within the KMZ file. That way you can share these details without having to reference the files through some link to the Internet. For KMZ files without images, the file size will be much smaller than the equivalent KML file.

Undersea features displayed by Gazetteer can be accessed by clients (like Google Earth) that support KML using the URL below. Use of this request returns a map file as an attachment that can be saved locally. If this request were invoked directly from a browser, for example, then the browser would generate a dialog allowing you to save the file. Once saved, such a file can be opened with Google Earth. This particular KMZ file displays the features as individual layers that can be toggled on or off.

http://maps.ngdc.noaa.gov/arcgis/rest/services/web_mercator/undersea_features/MapServer/KmlServer?Composite=false&amp;LayerIDs=0

There is also an image based KMZ file with faster display performance available here:

http://maps.ngdc.noaa.gov/arcgis/rest/services/web_mercator/undersea_features/MapServer/kml/mapImage.kmz