VDatum API Documentation

VDatum API Documentation describes how to use the APIs and includes code samples.

JSON - VDatum Full API

VDatum Full API Diagram
Response Elements
Request URL
Request parameters
Regions List
Horizontal Reference Frames List
Vertical Reference Frames List
Sample URL requests and responses

VDatum Full API Diagram

Response Elements

Element	Description
region	Region
s_h_frame	Source Horizontal Reference Frame
s_coor	Source Horizontal Coor. System
s_h_unit	Source Horizontal Unit
s_h_zone	Source Horizontal Zone (UTM, SPC)
s_v_frame	Source Vertical Reference Frame
s_v_unit	Source Vertical Unit
s_v_elevation	Source Vertical Elevation
s_v_geoid	Source Vertical GEOID model
s_x	Source X
s_y	Source Y
s_z	Source Z
t_h_frame	Target Horizontal Reference Frame.
t_coor	Target Horizontal Coor. System
t_h_unit	Target Horizontal Unit
t_h_zone	Target Horizontal Zone (UTM, SPC)
t_v_frame	Target Tidal Frame
t_v_unit	Target Vertical Unit
t_v_elevation	Target Vertical Elevation
t_v_geoid	Target Vertical GEOID model
epoch_in	Epoch - the input position
epoch_out	Epoch - the output position
t_x	Target X
t_y	Target Y
t_z	Target Z
uncertainty	Vertical Uncertainty (+/-)

Request URL

https://vdatum.noaa.gov/vdatumweb/api/convert[?s_x][&s_y][&s_z][&region][&s_h_frame][&s_coor][&s_h_unit][&s_h_zone][&s_v_frame][&s_v_unit][&s_v_elevation][&s_v_geoid][&t_h_frame][&t_coor][&t_h_unit][&t_h_zone][&t_v_frame][&t_v_unit][&t_v_elevation][&t_v_geoid][&epoch_in][&epoch_out]

Request parameters

Parameters	Definition
s_x (required)	Input Source X (Longitude or Easting or X) e.g. -124.422225, 235.577775, 387965.817, -2552393.98607 etc
s_y (required)	Input Source Y (Latitude or Northing or Y) e.g. 44.040218, 4877323.65984, -3788219.31101 etc
s_z (optional)	Input Source Z (Height or Z) e.g. 27.121, -3.649, 0.00, 4411305.243 etc Default value is 0
region (optional)	Input Region. (Regions List) e.g. ak, as, contiguous, gcnmi, prvi etc Default value is contiguous
s_h_frame (optional)	Input Source Horizontal Reference Frame. (Horizontal Reference Frames List) e.g. NAD27, NAD83_1986, NAD83_2011, NAD83_NSRS2007, NAD83_MARP00, NAD83_PACP00, WGS84_G1674, ITRF2014, IGS14, ITRF2008, IGS08, ITRF2005, IGS2005, WGS84_G1150, ITRF2000, IGS00, IGb00, ITRF96, WGS84_G873, ITRF94, ITRF93, ITRF92, SIOMIT92, WGS84_G730, ITRF91, ITRF90, ITRF89, ITRF88, WGS84_TRANSIT, WGS84_G1762 etc Default value is NAD83_2011
s_coor (optional)	Input Source Horizontal Coor system. e.g. geo, utm, spc, xyz Default value is geo
s_h_unit (optional)	Input Source Horizontal Unit. e.g. m, ft, us_ft Default value is m (meter)
s_h_zone (required if it is UTM or SPC)	Input Source Horizontal Zone (UTM or SPC). e.g. 18, 3900
s_v_frame (optional)	Input Source Vertical Reference Frame. (Vertical Reference Frames List) e.g. NAVD88, NGVD29, ASVD02, W0_USGG2012, GUVD04, NMVD03, PRVD02, VIVD09, CRD, EGM2008, EGM1996, EGM1984, XGEOID16B, XGEOID17B, XGEOID18B, XGEOID19B, IGLD85, LWD_IGLD85, OHWM_IGLD85, LMSL, MLLW, MLW, MTL, DTL, MHW, MHHW, LWD, NAD27, NAD83_1986, NAD83_2011, NAD83_NSRS2007, NAD83_MARP00, NAD83_PACP00, WGS84_G1674, ITRF2014, IGS14, ITRF2008, IGS08, ITRF2005, IGS2005, WGS84_G1150, ITRF2000, IGS00, IGb00, ITRF96, WGS84_G873, ITRF94, ITRF93, ITRF92, SIOMIT92, WGS84_G730, ITRF91, ITRF90, ITRF89, ITRF88, WGS84_TRANSIT, WGS84_G1762 etc Default value is NAVD88
s_v_unit (optional)	Input Source Vertical Unit. e.g. m, ft, us_ft Default value is m (meter)
s_v_elevation (optional)	Input Source Vertical Elevation. e.g. height, sounding Default value is height
s_v_geoid (optional)	Input Source Vertical GEOID model. e.g. geoid18, geoid12b, geoid12a, geoid09, geoid06, geoid03, geoid99, geoid96, egm2008, egm1996, egm1984, xgeoid16b, xgeoid17b, xgeoid18b, xgeoid19b, xgeoid20b Default value is geoid18
t_h_frame (optional)	Input Target Horizontal Reference Frame. (Horizontal Reference Frames List) e.g. NAD27, NAD83_1986, NAD83_2011, NAD83_NSRS2007, NAD83_MARP00, NAD83_PACP00, WGS84_G1674, ITRF2014, IGS14, ITRF2008, IGS08, ITRF2005, IGS2005, WGS84_G1150, ITRF2000, IGS00, IGb00, ITRF96, WGS84_G873, ITRF94, ITRF93, ITRF92, SIOMIT92, WGS84_G730, ITRF91, ITRF90, ITRF89, ITRF88, WGS84_TRANSIT, WGS84_G1762 etc Default value is NAD83_2011
t_coor (optional)	Input Target Horizontal Coor system. e.g. geo, utm, spc, xyz Default value is geo
t_h_unit (optional)	Input Target Horizontal Unit. e.g. m, ft, us_ft Default value is m (meter)
t_h_zone (required if it is SPC)	Input Target Horizontal Zone (SPC). e.g. 3900
t_v_frame (optional)	Input Target Vertical Reference Frame. (Vertical Reference Frames List) e.g. NAVD88, NGVD29, ASVD02, W0_USGG2012, GUVD04, NMVD03, PRVD02, VIVD09, CRD, EGM2008, EGM1996, EGM1984, XGEOID16B, XGEOID17B, XGEOID18B, XGEOID19B, IGLD85, LWD_IGLD85, OHWM_IGLD85, LMSL, MLLW, MLW, MTL, DTL, MHW, MHHW, LWD, NAD27, NAD83_1986, NAD83_2011, NAD83_NSRS2007, NAD83_MARP00, NAD83_PACP00, WGS84_G1674, ITRF2014, IGS14, ITRF2008, IGS08, ITRF2005, IGS2005, WGS84_G1150, ITRF2000, IGS00, IGb00, ITRF96, WGS84_G873, ITRF94, ITRF93, ITRF92, SIOMIT92, WGS84_G730, ITRF91, ITRF90, ITRF89, ITRF88, WGS84_TRANSIT, WGS84_G1762 etc Default value is NAVD88
t_v_unit (optional)	Input Target Vertical Unit. e.g. m, ft, us_ft Default value is m (meter)
t_v_elevation (optional)	Input Target Vertical Elevation. e.g. height, sounding Default value is height
t_v_geoid (optional)	Input Target Vertical GEOID model. e.g. geoid18, geoid12b, geoid12a, geoid09, geoid06, geoid03, geoid99, geoid96, egm2008, egm1996, egm1984, xgeoid16b, xgeoid17b, xgeoid18b, xgeoid19b, xgeoid20b Default value is geoid18
epoch_in (optional)	Epoch - the input position e.g. 1997.0 Default value is 0.0
epoch_out (optional)	Epoch - the output position e.g. 1997.0 Default value is 0.0

Regions List

Region	Region Description
ak	Alaska
seak	South East Alaska Tidal
as	American Samoa
contiguous	Contiguous United States
chesapeak_delaware	Chesapeake/Delaware Bay
westcoast	West Coast
gcnmi	Guam and Commonwealth of Northern Mariana Islands
hi	Hawaii
prvi	Puerto Rico and US Virgin Islands
sgi	Saint George Island
spi	Saint Paul Island
sli	Saint Lawrence Island

Horizontal Reference Frames List

Horizontal Frame Name	Horizontal Frame Description
NAD27	NAD 1927
NAD83_1986	NAD83 (1986)
NAD83_2011	NAD83_2011 - North American techtonic plate fixed
NAD83_NSRS2007	NAD83_NSRS2007 - NAD 83(NSRS2007) National Readjustment
NAD83_MARP00	NAD83 (MA11/MARP00) - Mariana tectonic plate fixed
NAD83_PACP00	NAD83 (PA11/PACP00) - Pacific tectonic plate fixed
WGS84_G1674	WGS84(G1674) - use ITRF2008
ITRF2014	International Terrestrial Reference System 2014
IGS14	International GNSS (Global Navigation Satellite Systems) Service of 2014
ITRF2008	International Terrestrial Reference System 2008
IGS08	International GNSS (Global Navigation Satellite Systems) Service of 2008
ITRF2005	International Terrestrial Reference System 2005
IGS2005	International GNSS (Global Navigation Satellite Systems) Service (IGS) of 2005
WGS84_G1150	WGS84(G1150) - use ITRF2000
ITRF2000	International Terrestrial Reference System 2000
IGS00	International GNSS(Global Navigation Satellite Systems) Service (IGS) of 2000
IGb00	NGS/IGS reference system of 2000
ITRF96	International Terrestrial Reference System 1996
WGS84_G873	WGS84(G873) - use ITRF96
ITRF94	International Terrestrial Reference System 1994
ITRF93	International Terrestrial Reference System 1993
ITRF92	International Terrestrial Reference System 1992
SIOMIT92	Scripps Institution of Oceanography /Massachusetts Inst. of Tech. 1992 (SIO/MIT 1992) - use ITRF91
WGS84_G730	WGS84(G730) - use ITRF91
ITRF91	International Terrestrial Reference System 1991
ITRF90	International Terrestrial Reference System 1990
ITRF89	International Terrestrial Reference System 1989
ITRF88	International Terrestrial Reference System 1988
WGS84_TRANSIT	WGS84(transit) - use NAD83_2011 (see NGS's HTDP)
WGS84_G1762	WGS84(G1762) - use IGS08
WGS84_G2139	WGS84(G2139) - use IGS14

Vertical Reference Frames List

Vertical Frame Name	Vertical Frame Description
NAVD88	North American Vertical Datum of 1988
NGVD29	National Geodetic Vertical Datum of 1929
ASVD02	American Samoa Vertical Datum of 2002
W0_USGG2012	Vertical datum of Hawaii (W0 from USGG2012)
GUVD04	Guam Vertical Datum of 2004
NMVD03	Northern Marianas Vertical Datum of 2003
PRVD02	Puerto Rico Vertical Datum of 2002
VIVD09	Virgin Island Vertical Datum of 2009
CRD	Columbia River Datum
EGM2008	EGM2008(WGS84_G1674)
EGM1996	EGM1996(WGS84_G1674)
EGM1984	EGM1984(WGS84_G1674)
XGEOID16B	xGEOID16b(IGS08)
XGEOID17B	xGEOID17b(IGS08)
XGEOID18B	xGEOID18b(IGS08)
XGEOID19B	xGEOID19b(IGS08)
XGEOID20B	xGEOID20b(IGS08)
IGLD85	The International Great Lakes Datum of 1985
LWD_IGLD85	The International Great Lakes LWD Datum of 1985
OHWM_IGLD85	The Ordinary High Water Mark (OHWM) relative to IGLD 1985
CRD	Columbia River Datum
LMSL	Local Mean Sea Level
MLLW	Mean Lower Low Water
MLW	Mean Low Water
MTL	Mean Tide Level
DTL	Diurnal Tide Level
MHW	Mean High Water
MHHW	Mean Higher High Water
LWD	Low Water Datum (non-tidal areas)
NAD27	NAD 1927
NAD83_1986	NAD83 (1986)
NAD83_2011	NAD83_2011 - North American techtonic plate fixed
NAD83_NSRS2007	NAD83_NSRS2007 - NAD 83(NSRS2007) National Readjustment
NAD83_MARP00	NAD83 (MA11/MARP00) - Mariana tectonic plate fixed
NAD83_PACP00	NAD83 (PA11/PACP00) - Pacific tectonic plate fixed
WGS84_G1674	WGS84(G1674) - use ITRF2008
ITRF2014	International Terrestrial Reference System 2014
IGS14	International GNSS (Global Navigation Satellite Systems) Service of 2014
ITRF2008	International Terrestrial Reference System 2008
IGS08	International GNSS (Global Navigation Satellite Systems) Service of 2008
ITRF2005	International Terrestrial Reference System 2005
IGS2005	International GNSS (Global Navigation Satellite Systems) Service (IGS) of 2005
WGS84_G1150	WGS84(G1150) - use ITRF2000
ITRF2000	International Terrestrial Reference System 2000
IGS00	International GNSS(Global Navigation Satellite Systems) Service (IGS) of 2000
IGb00	NGS/IGS reference system of 2000
ITRF96	International Terrestrial Reference System 1996
WGS84_G873	WGS84(G873) - use ITRF96
ITRF94	International Terrestrial Reference System 1994
ITRF93	International Terrestrial Reference System 1993
ITRF92	International Terrestrial Reference System 1992
SIOMIT92	Scripps Institution of Oceanography /Massachusetts Inst. of Tech. 1992 (SIO/MIT 1992) - use ITRF91
WGS84_G730	WGS84(G730) - use ITRF91
ITRF91	International Terrestrial Reference System 1991
ITRF90	International Terrestrial Reference System 1990
ITRF89	International Terrestrial Reference System 1989
ITRF88	International Terrestrial Reference System 1988
WGS84_TRANSIT	WGS84(transit) - use NAD83_2011 (see NGS's HTDP)
WGS84_G1762	WGS84(G1762) - use IGS08
WGS84_G2139	WGS84(G2139) - use IGS14

Sample URL requests and responses


{
"region": "CONTIGUOUS",
"s_h_frame": "NAD83_2011",
"s_coor": "geo",
"s_h_unit": "",
"s_h_zone": "",
"s_v_frame": "NAVD88",
"s_v_unit": "m",
"s_v_elevation": "height",
"s_v_geoid": "geoid18",
"s_x": "-75.211",
"s_y": "36.129",
"s_z": "0.0",
"t_h_frame": "NAD83_2011",
"t_coor": "geo",
"t_h_unit": "",
"t_h_zone": "",
"t_v_frame": "MLLW",
"t_v_unit": "m",
"t_v_elevation": "height",
"t_v_geoid": "geoid18",
"epoch_in": "0.0",
"epoch_out": "0.0",
"t_x": "-75.211",
"t_y": "36.129",
"t_z": "0.629",
"uncertainty": "0.081"
}
					
{
"region": "CONTIGUOUS",
"s_h_frame": "NAD83_2011",
"s_coor": "geo",
"s_h_unit": "",
"s_h_zone": "",
"s_v_frame": "NAVD88",
"s_v_unit": "m",
"s_v_elevation": "height",
"s_v_geoid": "geoid18",
"s_x": "-75.211",
"s_y": "36.129",
"s_z": "0.0",
"t_h_frame": "NAD83_2011",
"t_coor": "geo",
"t_h_unit": "",
"t_h_zone": "",
"t_v_frame": "MHW",
"t_v_unit": "m",
"t_v_elevation": "height",
"t_v_geoid": "geoid18",
"epoch_in": "0.0",
"epoch_out": "0.0",
"t_x": "-75.211",
"t_y": "36.129",
"t_z": "-0.342",
"uncertainty": "0.076"
}
					
{
"region": "CONTIGUOUS",
"s_h_frame": "NAD83_2011",
"s_coor": "geo",
"s_h_unit": "",
"s_h_zone": "",
"s_v_frame": "NAVD88",
"s_v_unit": "us_ft",
"s_v_elevation": "height",
"s_v_geoid": "geoid18",
"s_x": "-75.46803",
"s_y": "35.602986",
"s_z": "12.33",
"t_h_frame": "NAD83_2011",
"t_coor": "geo",
"t_h_unit": "",
"t_h_zone": "",
"t_v_frame": "MLLW",
"t_v_unit": "us_ft",
"t_v_elevation": "height",
"t_v_geoid": "geoid18",
"epoch_in": "0.0",
"epoch_out": "0.0",
"t_x": "-75.46803",
"t_y": "35.602986",
"t_z": "12.808",
"uncertainty": "0.251"
}
					
{
"region": "CHESAPEAK_DELAWARE",
"s_h_frame": "NAD27",
"s_coor": "geo",
"s_h_unit": "",
"s_h_zone": "",
"s_v_frame": "NGVD29",
"s_v_unit": "m",
"s_v_elevation": "height",
"s_v_geoid": "geoid18",
"s_x": "-74.852064",
"s_y": "39.594706",
"s_z": "0.0",
"t_h_frame": "NAD83_2011",
"t_coor": "geo",
"t_h_unit": "",
"t_h_zone": "",
"t_v_frame": "NAVD88",
"t_v_unit": "m",
"t_v_elevation": "height",
"t_v_geoid": "geoid18",
"epoch_in": "0.0",
"epoch_out": "0.0",
"t_x": "-74.8516763",
"t_y": "39.5948273",
"t_z": "-0.372",
"uncertainty": "0.050"
}
					

{
"region": "WESTCOAST",
"s_h_frame": "NAD83_2011",
"s_coor": "geo",
"s_h_unit": "",
"s_h_zone": "",
"s_v_frame": "NAVD88",
"s_v_unit": "m",
"s_v_elevation": "height",
"s_v_geoid": "geoid18",
"s_x": "-124.1",
"s_y": "44.9",
"s_z": "0.0",
"t_h_frame": "IGS14",
"t_coor": "geo",
"t_h_unit": "",
"t_h_zone": "",
"t_v_frame": "MLLW",
"t_v_unit": "m",
"t_v_elevation": "height",
"t_v_geoid": "geoid18",
"epoch_in": "0.0",
"epoch_out": "0.0",
"t_x": "-124.100016",
"t_y": "44.900005",
"t_z": "0.155",
"uncertainty": "0.094"
}
					

	Samples
1	Region: contiguous Request https://vdatum.noaa.gov/vdatumweb/api/convert?s_x=-75.211&s_y=36.129 JSON output { "region": "CONTIGUOUS", "s_h_frame": "NAD83_2011", "s_coor": "geo", "s_h_unit": "", "s_h_zone": "", "s_v_frame": "NAVD88", "s_v_unit": "m", "s_v_elevation": "height", "s_v_geoid": "geoid18", "s_x": "-75.211", "s_y": "36.129", "s_z": "0.0", "t_h_frame": "NAD83_2011", "t_coor": "geo", "t_h_unit": "", "t_h_zone": "", "t_v_frame": "MLLW", "t_v_unit": "m", "t_v_elevation": "height", "t_v_geoid": "geoid18", "epoch_in": "0.0", "epoch_out": "0.0", "t_x": "-75.211", "t_y": "36.129", "t_z": "0.629", "uncertainty": "0.081" }
2	Region: contiguous Request https://vdatum.noaa.gov/vdatumweb/api/convert?s_x=-75.211&s_y=36.129&t_v_frame=MHW JSON output { "region": "CONTIGUOUS", "s_h_frame": "NAD83_2011", "s_coor": "geo", "s_h_unit": "", "s_h_zone": "", "s_v_frame": "NAVD88", "s_v_unit": "m", "s_v_elevation": "height", "s_v_geoid": "geoid18", "s_x": "-75.211", "s_y": "36.129", "s_z": "0.0", "t_h_frame": "NAD83_2011", "t_coor": "geo", "t_h_unit": "", "t_h_zone": "", "t_v_frame": "MHW", "t_v_unit": "m", "t_v_elevation": "height", "t_v_geoid": "geoid18", "epoch_in": "0.0", "epoch_out": "0.0", "t_x": "-75.211", "t_y": "36.129", "t_z": "-0.342", "uncertainty": "0.076" }
3	Region: contiguous Request https://vdatum.noaa.gov/vdatumweb/api/convert?s_v_unit=us_ft&s_x=-75.46803&s_y=35.602986&s_z=12.33&t_v_frame=MLLW&t_v_unit=us_ft JSON output { "region": "CONTIGUOUS", "s_h_frame": "NAD83_2011", "s_coor": "geo", "s_h_unit": "", "s_h_zone": "", "s_v_frame": "NAVD88", "s_v_unit": "us_ft", "s_v_elevation": "height", "s_v_geoid": "geoid18", "s_x": "-75.46803", "s_y": "35.602986", "s_z": "12.33", "t_h_frame": "NAD83_2011", "t_coor": "geo", "t_h_unit": "", "t_h_zone": "", "t_v_frame": "MLLW", "t_v_unit": "us_ft", "t_v_elevation": "height", "t_v_geoid": "geoid18", "epoch_in": "0.0", "epoch_out": "0.0", "t_x": "-75.46803", "t_y": "35.602986", "t_z": "12.808", "uncertainty": "0.251" }
4	Region: Chesapeake/Delaware Bay Request https://vdatum.noaa.gov/vdatumweb/api/convert?region=chesapeak_delaware&s_y=39.594706&s_x=-74.852064& s_h_frame=NAD27&s_v_frame=NGVD29&s_v_unit=m&height=0.0&t_v_frame=NAVD88&t_v_unit=m JSON output { "region": "CHESAPEAK_DELAWARE", "s_h_frame": "NAD27", "s_coor": "geo", "s_h_unit": "", "s_h_zone": "", "s_v_frame": "NGVD29", "s_v_unit": "m", "s_v_elevation": "height", "s_v_geoid": "geoid18", "s_x": "-74.852064", "s_y": "39.594706", "s_z": "0.0", "t_h_frame": "NAD83_2011", "t_coor": "geo", "t_h_unit": "", "t_h_zone": "", "t_v_frame": "NAVD88", "t_v_unit": "m", "t_v_elevation": "height", "t_v_geoid": "geoid18", "epoch_in": "0.0", "epoch_out": "0.0", "t_x": "-74.8516763", "t_y": "39.5948273", "t_z": "-0.372", "uncertainty": "0.050" }
5	Region: West Coast Request https://vdatum.noaa.gov/vdatumweb/api/convert?region=westcoast&s_x=-124.1&s_y=44.9&t_h_frame=IGS14 JSON output { "region": "WESTCOAST", "s_h_frame": "NAD83_2011", "s_coor": "geo", "s_h_unit": "", "s_h_zone": "", "s_v_frame": "NAVD88", "s_v_unit": "m", "s_v_elevation": "height", "s_v_geoid": "geoid18", "s_x": "-124.1", "s_y": "44.9", "s_z": "0.0", "t_h_frame": "IGS14", "t_coor": "geo", "t_h_unit": "", "t_h_zone": "", "t_v_frame": "MLLW", "t_v_unit": "m", "t_v_elevation": "height", "t_v_geoid": "geoid18", "epoch_in": "0.0", "epoch_out": "0.0", "t_x": "-124.100016", "t_y": "44.900005", "t_z": "0.155", "uncertainty": "0.094" }