Dev: SM: Calculations API

From AAT Wiki
Jump to: navigation, search

Introduction

The Calculations API allows you to do cartography calculations.

Calling

https://www.streetmaps.co.za/api/calc?op1=OP&op1.arg1=ARG&op2=...[&fmt=FMT[&jscb=JSCB]]

Arguments are passed via a GET or POST (for larger data payloads)

opN (String) Any number of operations can be passed in. They will be calculated and returned. Current operations are:
  • area - Calculate the area of a polygon in "arg1"
opN.argM (String) Each operation will have one or more arguments. The "opN" portion of this parameter will match the opN that specifies the operation type, and argM will start from arg1 and progress to argX where X = number of arguments.
  • area accepts 1 argument, which is a comma delimited lists of coordinates in the format x1,y1,x2,y2,...xN,yN
fmt (string) If not specified, "xml" is the default. Possible values are
  • xml - data is returned in XML format (see below)
  • js - data is returned as a JSON call, using the "jscb" as the JSON callback function name (see below)

Results From XML Call

https://www.streetmaps.co.za/api/calc?op1=area&op1.arg1=27.9421380000,-26.0674820000,27.9423110000,-26.0674280000,27.9424830000,-26.0673740000,27.9425760000,-26.0674920000,27.9426680000,-26.0676090000,27.9423830000,-26.0677930000,27.9423250000,-26.0677190000,27.9421380000,-26.0674820000
<?xml version="1.0" encoding="ISO-8859-1" ?> 
<results> 
  <result seq=1 operation="area" result="1300.6" result_unit="m2" error=False  /> 
</results>

The XML is fairly self explanatory; here is a brief description of some the important tags

seq Corresponds to the "N" in the opN parameter
result Result of the calculation
  • area - a floating point number denoting the area in m2
result_unit The unit of the result, depending on the operation
  • area - m2 (meters squared)
error True or False depending on how the calculation went. Should this be "true", there will be parse_error and/or calc_error values that will explain what the error was.

Results From JSON Call

view-source:https://beta.streetmaps.co.za/api/calc?op1=area&op1.arg1=27.9421380000,-26.0674820000,27.9423110000,-26.0674280000,27.9424830000,-26.0673740000,27.9425760000,-26.0674920000,27.9426680000,-26.0676090000,27.9423830000,-26.0677930000,27.9423250000,-26.0677190000,27.9421380000,-26.0674820000&fmt=js&jscb=GeoCalc
GeoCalc({results:[{seq:1,operation:"area",result:"1300.6",result_unit:"m2",error:false}]});