Documentation Of JS API

After registration you receive an API key which can be used to include the Javascript API into your HTML page as follows:


<script type="text/javascript" src="http://topocoding.com/api/getapi_v1.php?key=BGMCCPGOZNKXPZC"></script>

The API contains the following functions:

topoToFeets( meters )

conversion from meters to feets

topoParseAngle( string )

converts the combined form of latitude or longitude (e.g. 50°24'37.22"N ) to real number

topoGetAltitude( lat, lon, action, context, timeout )

sends a query to the server to find the altitude of the place with GPS coordinates (lat,lon). When the server responds the event "action" is called with the altitude as a parameter. Context is an optional parameter - if specified, it is passed to "action" as a second parameter. The use of context might help you to avoid memory leaks from Javascript closures. Timeout is an optional parameter, it specifies the maximum time in miliseconds that the client waits for server response. When the timeout expires, the "action" event is called with altitude parameter set to null. If timeout is not specified, the "action" might not be called at all.

topoGetAltitudes( quadruples, timeout )

sends multiple queries at once. "Quadruples" is an array, each element of this array contains latitude, longitude, action and - optionally - context. See the description of topoGetAltitude() parameters. The quadruples are split into groups of at most 280, each group is sent as one request.

topoComputeDistance( lat1, lon1, lat2, lon2 )

computes the shortest distance in km between a place with GPS coordinates (lat1,lon1) and a place with GPS coordinates (lat2,lon2). The computation is performed on client side, the curvature of geoid is considered,.

topoComputeIntermediate( lat1, lon1, lat2, lon2 , fraction )

returns an array containing the coordinates of a place which lies on the shortest path between a place with GPS coordinates (lat1,lon1) and a place with GPS coordinates (lat2,lon2). The ratio determines the exact position of the resulting place, for example 0.5 means the middle. The computation is performed on client side, the curvature of geoid is considered,.

topoDrawGraph( divElement, coordinates, width, height, english )

draws an altitude profile of a path connecting places with given coordinates. "DivElement" refers to an HTML element of type "DIV", which is used as a placeholder for created PNG image. Optional parameters width and height specify the size of image, the default size is 600x250. NEW: english is an optional flag that switches units from meters+kilometers to feets+miles

topoResampleCoordinates( points )

returns the array of points constructed by extending the path with intermediate points.

Example

To demonstrate the use of these API functions, we provide a full source code of the example from the topocoding.com homepage. Modify the topocoding API key (line 15) in this file to use your own registered keys.

<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no">
    <meta charset="utf-8">
    <style>
      html, body, #map-canvas {
        height: 100%;
        margin: 0px;
        padding: 0px
      }
    </style>
    <script src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false"></script>
    <script type="text/javascript" src="https://topocoding.com/api/getapi_v1.php?key=BGMCCPGOZNKXPZC"></script>
    <script>
var map;
var geocoder;
var points = new Array();
var coordinates = new Array();
var topoPath;
var coordInfoWindow;

function redrawPath() {
  if ( points.length > 0 ) {
    topoPath.setPath(points);
    topoPath.setMap(map);

    topoGetAltitude( points[ points.length - 1 ].lat(), points[ points.length - 1 ].lng(), function( altitude ) {
      coordInfoWindow.setContent("Altitude = <b>" + altitude + "</b> m" + " / <b>" + Math.round( topoToFeets( altitude ) ) + "</b> ft");
      coordInfoWindow.setPosition(points[ points.length - 1 ]);
      coordInfoWindow.open(map);
    } );
  } else {
     coordInfoWindow.close();
     topoPath.setMap(null);
  }
}

function undoPoint() {
  if ( points.length > 0 )
    {
      points.length = points.length - 1;
      coordinates.length = coordinates.length - 1;
      redrawPath();
    }  
}

function initialize() {
  geocoder = new google.maps.Geocoder();
  var mapOptions = {
    zoom: 4,
    center: new google.maps.LatLng(49, 17),
    mapTypeId: google.maps.MapTypeId.ROADMAP
  };
  map = new google.maps.Map(document.getElementById('map-canvas'),
      mapOptions); 

  topoPath = new google.maps.Polyline({
    geodesic: true,
    strokeColor: '#0000FF',
    strokeOpacity: 0.5,
    strokeWeight: 5,
    map: map
  });

  coordInfoWindow = new google.maps.InfoWindow();

  google.maps.event.addListener(map, 'click', function(event) {
      points[ points.length ] = event.latLng;
      coordinates[ coordinates.length ] = [ event.latLng.lat(), event.latLng.lng() ];
      redrawPath();
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

function updateGraph( english )
{
  if ( coordinates.length < 2 )
    alert( 'Add more points by clicking the map.' );
  else
    topoDrawGraph( document.getElementById("graph"), coordinates, 600, 250, english );
}

function addPoint(lat,lon) {
 var xLat = topoParseAngle( lat );
 var xLon = topoParseAngle( lon );
 if ( ( !xLat ) || ( !xLon ) ) {
   alert( "Invalid syntax" );
 } else {
  var point = new google.maps.LatLng( xLat, xLon );
  points[ points.length ] = point;
  coordinates[ coordinates.length ] = [ point.lat(), point.lng() ];
  redrawPath();
 }
}

function centerPoint(lat,lon) {
  var xLat = topoParseAngle( lat );
  var xLon = topoParseAngle( lon );
  if ( ( !xLat ) || ( !xLon ) ) {
    alert( "Invalid syntax" );
  } else {
    var point = new google.maps.LatLng( xLat, xLon );
    map.setCenter(point);
  }
}

function addAddress(address) {
  geocoder.geocode( { 'address': address}, function(results, status) {
    if (status == google.maps.GeocoderStatus.OK) {
        points[ points.length ] = results[0].geometry.location;
        coordinates[ coordinates.length ] = [ results[0].geometry.location.lat(), results[0].geometry.location.lng() ];
        redrawPath();
    } else {
      alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

function centerAddress(address) {
  geocoder.geocode( { 'address': address}, function(results, status) {
    if (status == google.maps.GeocoderStatus.OK) {
        map.setCenter(results[0].geometry.location);
    } else {
      alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

    </script>
  </head>
  <body>
    <h4>This example shows the use of function topoGetAltitude() for reading the altitude information from the server,
    and the use of topoDrawGraph() function for drawing the altitude profile.</h4>
    By clicking the map you add points to the path whose altitude profile can be displayed using the first button.
    The altitude profile may be used for example to evaluate the degree of difficulty for given path, or 
    for verifying the visibility of the WiFi access point.<br><br>
    <div id="map-canvas" style="width: 600px; height: 450px; border: 1px silver solid;"></div>
    <form>
    <INPUT TYPE=checkbox NAME=chkEnglish VALUE="">English units
    <INPUT TYPE=button VALUE="Update altitude profile" ONCLICK="updateGraph(chkEnglish.checked)">
    <INPUT TYPE=button VALUE="Remove last path segment" ONCLICK="undoPoint()">
    <div id="graph"></div>
    </form>
    <br>
    <form>
    <b>Address:</b>
    <INPUT TYPE=text NAME="txtAddress" size=45>
    <INPUT TYPE=button VALUE="Center to address" ONCLICK="centerAddress(txtAddress.value);">
    <INPUT TYPE=button VALUE="Add address" ONCLICK="addAddress(txtAddress.value)">
    <br>
    <br>
    <b>Point:</b>
    Latitude = <INPUT TYPE=text NAME="txtLatitude" size=14>, Longitude = <INPUT TYPE=text NAME="txtLongitude" size=14>
    <INPUT TYPE=button VALUE="Center to point" ONCLICK="centerPoint(txtLatitude.value, txtLongitude.value)">
    <INPUT TYPE=button VALUE="Add point" ONCLICK="addPoint(txtLatitude.value, txtLongitude.value)">
    </form>
</html>
©2012 TOPOCODING.com