Because of unauthorized, high volume use of this API, only requests with two points -- from 44.3,-69.1 to 44.4,-69.2, as in the examples below -- will work without authorization. If you are interested in using the API, please contact us.

• This API is freely available for low-volume, non-commercial use. Contact us to set up an identifier to use in the &src= URL parameter.
• If you plan to incorporate these calls in regression tests, note that we sometimes make changes to our computations, so the same query may yield different results over time.
• Our Fixed Wireless Site, designed for wireless Internet service providers, can be used for line of sight analysis of point-to-point links.

Background

This API request returns the elevations on the great circle path between two points. There are options to specify the number of intermediate points or the spacing between them.

The elevation data is the same SRTM dataset (more info) we use across the site; it covers latitudes 60°N to 54°S with one meter vertical resolution, and has horizontal resolution of 1 arc-second (roughly 30m) in the USA and 3 arc-seconds (100m) in the rest of the world.

Request

Use the URL

    http://www.heywhatsthat.com/api/path-elev.csv?src=XXXX&pt0=999,999&pt1=99,999

The parameters are:

Required
src	an identifier we can use to track usage; please pick something short and let us know what it is
pt0	start of the path latitude,longitude
pt1	end of the path
Optional
showlatlon	set to 1 if you want the latitude and longitude of the intervening points
	Choose at most one of the following. If none of these options are specified, default is to output 100 points.
n	number of points desired, including the endpoints
spacing	distance, in meters, between points. This value will be reduced as necessary to exactly fit an integral number of segments
precisespacing	distance, in meters, between points. This spacing will be used between all but the final two points; their separation will be whatever is necessary to complete the path

You can specify more than two points (eg. &pt0=99,999&pt1=99,999&pt2=99,999&...) if your path has multiple segments.

The response will be a CSV format file, or empty if an error occurred (Error messages appear in the HTTP header X-App-Status). Each line of the response corresponds to a point along the path. The columns are range (in meters) from the start point, elevation (meter above mean sea level) of the point, and optionally, the point's latitude and longitude.

Note that we return the nearest SRTM elevation value; ie. we do not currently interpolate between SRTM gridpoints.

Line of Sight

Add the parameter &los_amsl=1 to add the elevation above mean sea level of the line of sight between your points, or &los_agl=1 for the elevation above ground. If you want to place the endpoints above ground level, you can follow the syntax we use for the Profiler API, where we use &ptX=lat,lon,line color,elevation,marker color, and don't include any colors (but do use the correct number of commas), and include &groundrelative=1 if the elevations you provide are relative to ground rather than sea level.

Examples

$ curl "http://www.heywhatsthat.com/api/path-elev.csv?src=zzz&pt0=44.3,-69.1&pt1=44.4,-69.2"
"Distance (m)","Elevation (m amsl)"Latitude,Longitude
0.00,44.00
138.12,44.00
276.24,44.00
    .
    .
    .
13397.56,56.00
13535.68,58.00
13673.79,66.00

$ curl "http://www.heywhatsthat.com/api/path-elev.csv?src=zzz&pt0=44.3,-69.1&pt1=44.4,-69.2&n=7"
"Distance (m)","Elevation (m amsl)"
0.00,44.00
2278.97,102.00
4557.93,206.00
6836.90,63.00
9115.86,61.00
11394.83,68.00
13673.79,64.00

$ curl "http://www.heywhatsthat.com/api/path-elev.csv?src=zzz&pt0=44.3,-69.1&pt1=44.4,-69.2&n=7&spacing=5000&showlatlon=1"
"Distance (m)","Elevation (m amsl)",Latitude,Longitude
0.00,56.00,44.300000,-69.100000
4557.93,233.00,44.333343,-69.133295
9115.86,72.00,44.366676,-69.166629
13673.79,72.00,44.400000,-69.200000

$ curl "http://www.heywhatsthat.com/api/path-elev.csv?src=zzz&pt0=44.3,-69.1&pt1=44.4,-69.2&n=7&precisespacing=5000&showlatlon=1"
"Distance (m)","Elevation (m amsl)",Latitude,Longitude
0.00,56.00,44.300000,-69.100000
5000.00,233.00,44.336576,-69.136527
10000.00,68.00,44.373141,-69.173099
13673.79,72.00,44.400000,-69.200000

     Line of sight in meters above ground, from a point 2m above the ground to a point 10m above the ground:
$ curl "http://www.heywhatsthat.com/api/path-elev.csv?src=zzz&pt0=44.3,-69.1,,2&pt1=44.4,-69.2,,10&groundrelative=1&n=7&los_agl=1"
"Distance (m)","Elevation (m amsl)","LOS height (m amsl)"
0.00,44.00,2.00
2278.97,102.00,-52.75
4557.93,205.00,-151.80
6836.90,63.00,-5.15
9115.86,62.00,1.20
11394.83,69.00,0.25
13673.79,66.00,10.00

     Same as above, with line of sight given in meters above mean sea level:
$ curl "http://www.heywhatsthat.com/api/path-elev.csv?src=zzz&pt0=44.3,-69.1,,2&pt1=44.4,-69.2,,10&groundrelative=1&n=7&los_amsl=1"
"Distance (m)","Elevation (m amsl)","LOS height (m amsl)"
0.00,44.00,46.00
2278.97,102.00,49.25
4557.93,205.00,53.20
6836.90,63.00,57.85
9115.86,62.00,63.20
11394.83,69.00,69.25
13673.79,66.00,76.00