Dev: SM: Generate Static Map Image

From AAT Wiki
Jump to: navigation, search

AAT HTTP and XML Static Map Image Interface (Beta)

XML Call Details

  • Can be sent through as either a POST or GET.
  • For ease of use, any field name may be used to refer to the content, the page will concatenate the contents of all form fields, in order, into the XML request
  • XML Call Structure
<XMLAPI>
   <COMMAND name="commandname">
      <PARAMETER name="parmname">
      ...
   </COMMAND>
</XMLAPI>

HTTP Call Details

  • All commands supported by the XML interface are available to the HTTP call. The only difference is in the way the command is put together.
  • There are limits on the length of the command in this case, and they're usually imposed by the client-side browsers and/or proxy servers. There's no practical limit on the server side, but users of this facility must be aware of potential length limits.
  • Only one command per call is allowed on the HTTP interface
  • The format of the HTTP interface is

static.aspx?api=c&command=<CMDNAME>&<parmname>=symbol:value!symbol:value...

  • All parameter details and rules remain the same between the XML and HTTP interfaces.
  • A practical example would be the XML fragment
<PARAMETER name="image" service="base" x="28.5" y="-25.5" scaleFactor="2.0" width="450" height="300" showMarker="false" />
<PARAMETER name="point" x="28.5" y="-25.5" marker="Wingdings|128|20|255,0,0" label="test" labelFont="Arial|16|0,0,0" back="glowing|0,0,255" />
<PARAMETER name="line" coords="27 -25.52;30 -25.52;29 -27.02" marker="255,0,0|solid|3" />
<PARAMETER name="circle" x="28.52" y="-25.52" radius="0.5" marker="0,255,0|solid|3" />

translating to

static.aspx?api=c&image=service:base!x:28.5!y:-25.5!scaleFactor:2.0!width:450!height:300!showMarker:false&point=x:28.5!y:-25.5!marker:Wingdings|128|20|255,0,0!label:test!labelFont:Arial|16|0,0,0!back:glowing|0,0,255&circle=x:28.52!y:-25.52!radius:2!marker:0,255,0|solid|3

Command – GenerateMap

“image” parameter attributes:

service string (R) The "look and feel" of the map - Possible values are:
  • base = the base street map
  • imagery = satellite imagery (if available)
  • hybrid = a transparent road overlay to be placed over the imagery
x Double (R) The longitude (x-coordinate) of the map center point in decimal degrees (optional)
y Double (R) The latitude (y-coordinate) of the map center point in decimal degrees (optional)
scaleFactor Double (O) The "zoom level"; this is the number of degrees from the center of the map to the nearest edge, ie the "radius" of the area that the map covers.
width Integer (R) The width (horizontal distance) of the required image in pixels
height Integer (R) The height (vertical distance) of the required image in pixels
showMarker String (O) (“true/false”) Whether a reticule type marker must be displayed at the center point of the map. This parameter is useful if the map was generated from the results of a street search, as the street name label might not always be visible at the required minScaleFactor. If this parameter is omitted, the marker is shown.

“point” parameter attributes:

x Double (R) The longitude (x-coordinate) of the point that must be placed
y Double (R) The latitude (x-coordinate) of the point that must be placed
marker String (R) Contains information on how the point must be styled. Points can be styled with any character from a TrueType (or OpenType) font library. All standard MS Windows font families can be taken as installed, but if an unusual or specific font must be used the font must be supplied to Mapit for scrutiny and installation.

The marker string has the following parts separated by a ‘|’ (pipe) character:

  • Typeface: The typeface from which the character must be selected, e.g. ‘Wingdings’. The font name must be specified exactly (including capitalization) as the name appears in any MS Windows font dialogue box.
  • Character: The decimal character index.
  • Font Size: The font size in points.
  • Colour: The font colour as an RGB triplet separated by commas, e.g. ‘0,0,255’ for blue.
label String (O) The text for an optional label. If the text must wrap to a second line include a CR LF combination in the string.
labelFont String (R if label is present, otherwise ignored) Contains information on how the label must be styled. Text can be displayed in any TrueType (or OpenType) typeface. All standard MS Windows font families can be taken as installed, but if an unusual or specific font must be used the font must be supplied to Mapit for scrutiny and installation.

The labelFont string has the following parts separated by a ‘|’ (pipe) character:

  • Typeface: The with which the label must be rendered, e.g. ‘Arial’. The font name must be specified exactly (including capitalization) as the name appears in any MS *Windows font dialogue box.
  • Font Size: The font size in points.
  • Colour: The font colour as an RGB triplet separated by commas, e.g. ‘0,0,255’ for blue.
back String (O) An optional background effect for the label to make it stand out from the map background. If a background effect is not specified the label text will be drawn directly onto the map image.

The back string has the following parts separated by a ‘|’ (pipe) character:

  • Back Type: A string representing the background effect required:
    • glowing: The text is drawn with a halo of the specified colour.
    • blockout: The text is drawn with a box of the specified colour behind it.
    • outline: The text is drawn with an outline of the letters of the specified colour.
    • shadow: The text is drawn with a drop shadow of the specified colour.
  • Back Colour: The colour as an RGB triplet separated by commas, with which the back effect must be drawn, e.g. ‘0,0,255’ for a blue effect.

“line” parameter attributes:

coords String (R) Contains the coordinates for the line nodes (x,y values where the line segments join). Can be as many as desired but the x (longitude) and y (latitude) value of each pair must be seperated by a space, and each of the pairs must be seperated by a semicolon.
marker String (R) Contains information on how the line must be styled.

The marker string has the following parts separated by a ‘|’ (pipe) character:

  • Colour: The line colour as an RGB triplet separated by commas, e.g. ‘0,0,255’ for blue.
  • Type: The type of line symbol which should be used to graphically draw the line. This can be either solid, dash, dot, dash_dot, or dash_dot_dot.
  • Width: The line width in pixels.

“circle” parameter attributes:

x Double (R) Longitude (x-coordinate) of the center point of the circle.
y Double (R) Longitude (x-coordinate) of the center point of the circle.
radius Double (R) Radius of the circle in decimal degrees. Currently, this is the only supported measurement unit. This unit will later be changed to metres or kilometers.
marker String (R) Contains information on how the circle must be styled.

The marker string has the following parts separated by a ‘|’ (pipe) character:

  • Colour: The line colour as an RGB triplet separated by commas, e.g. ‘0,0,255’ for blue.
  • Type: The type of line symbol which should be used to graphically draw the circle. This can be either solid, dash, dot, dash_dot, or dash_dot_dot.
  • Width: The circle line width in pixels.