+27 87 310 6400 | products@afrigis.co.za
bclose

Static Maps

The fastest way to embed a simple, pretty map into a website, mobile application, reports and more.
StaticMaps_long

AfriGIS Static Maps allows users to generate map images on the fly. These map images can be used in a wide range of solutions like websites, social networks, mobile applications, reports, invoices and many more.

The map image is constructed by building up a URL containing the information to generate the image.

Key features:

  • Choose between a variety of map types (imagery, hybrid, map)
  • Specify a custom width & height for your map
  • Overlay pre-defined icons of your own
  • Draw polygons and polylines on the map
  • Add routing to the map
  • No JavaScript or other framework dependency makes it extremely easy to use.

See also:

API documentation

1 Introduction

2 Parameters specification

3 Mandatory/required parameters

4 Optional parameters

5 Additional parameters

Appendix A – ‘KnownColors’

Appendix B – ‘ASP.NET fonts’

1 Introduction

AfriGIS Static Maps allow users to customise a map which can be placed on a web page, blogs, social feeds (e.g. Facebook), applications, or any other digital property. This is a simpler way of producing map images, instead of embedding a fully functional (zoom and pan) map on a website using the AfriGIS JavaScript API or any other map provider, which has a large overhead.

The Static Maps web service is called with a simple HTTP request with various parameters, for example in the <img> tag:
<img src=”https://api.afrigis.co.za/StaticMap/?centre=x:28.256111,y:-25.808611&zoom=12&key=[YOUR_KEY]/trial” />

This will return a map image similar to the one below, which can then be extended in numerous ways:

Droppin

To access any of the AfriGIS web service APIs, you will need to sign up for a free trial account to obtain a key and shared secret. Please sign up here: https://saasregistration.afrigis.co.za/.

You will need to provide:

  • your mobile number – an OTP (one-time password) will be sent to it,
  • your email address – the key and secret will be emailed to you, as well as any future communications regarding your trial account.

 

2 Parameters specification

There are a number of parameters that can be set to adjust the position, style or overlaid objects of the image.

Level Name Multiple tokens separated by Token followed by
1 parameters ampersand (‘&’) character equals (‘=’) character
2 attributes semicolon (‘;’) character colon (‘:’) character
3 waypoints vertical bar/pipe (‘|’) character colon (‘:’) character
4 coordinates and parts of addresses comma (‘,’) character N/A

The parameters, attributes, waypoints, coordinates and parts of addresses are all case insensitive.

3 Mandatory/required parameters

The position of the map image is determined by two mutually exclusive parameter options: either centre&zoom or bbox. Only one of these parameter options must be chosen.

3.1 Centre&Zoom

Most people think of location in terms of an address, e.g. 446 Rigel Ave, Pretoria, so the most natural way to describe a map would be to centre it on an address and then to specify how much of the map to view by using the zoom parameter. For example:
https://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
zoom_param

If there is no obvious or known address to centre the map on, longitude and latitude coordinates may be used instead.
The location attribute will be comma delimited, with 2 tokens x and y (representing longitude and latitude respectively) each followed by the colon (‘:’) assignment character and a positive or negative number. The order of the tokens is not important, for example:
https://api.afrigis.co.za/StaticMap/?centre=x:28.256111,y:-25.808611&zoom=12&key=[YOUR_KEY]/trial
https://api.afrigis.co.za/StaticMap/?centre=y:-25.808611,x:28.256111&zoom=12&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.

zoom_param

The longitude parameter x ranges from -180 to 180, and the latitude parameter y ranges from -90 to 90.

The zoom parameter (1 to 20) varies from 1 being the entire world and 20 being the closest and most detailed zoom level.

3.2 BBox (Bounding box)

Alternatively, the sides of the bounding box may be referred to as 4 tokens: l, b, r and t (representing left [minimum longitude], bottom [minimum latitude], right [maximum longitude] and top [maximum latitude] respectively) each followed by the colon (‘:’) assignment character and a positive or negative number. All 4 tokens are mandatory and their order is not important. For example:
https://api.afrigis.co.za/StaticMap/?bbox=l:28.2,b:-25.9,r:28.3,t:-25.8&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
The parameters are: Bottom Left Longitude (-180 to 180), Bottom Left Latitude (-90 to 90), Top Right Longitude (-180 to 180), Top Right Latitude (-90 to 90). The bottom left longitude and latitude must always be less than the top right longitude and latitude.
Boundingboxparam

No zoom level is required because the extent of the bounding box is already specified.

3.3 Auto default

Where the optional parameters marker, icon, polyline, polygon or routing have been specified, the bounding box can be automatically calculated by specifying bbox=Auto, which will calculate the optimal bounding box incorporating all the marker, icon, polyline, polygon or directions objects, plus a reasonable 10% margin on each side. For example:
https://api.afrigis.co.za/StaticMap/?bbox=Auto&polyline=waypoints:446+Rigel+Ave,Pretoria|x:28.26,y:-25.80|Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
AddPolyline

bbox=Auto is the default if no centre&zoom or bbox parameter is supplied, however, where there is only a single point to be encompassed, a default zoom level of 1 is used, which would display the entire world. For example:
https://api.afrigis.co.za/StaticMap/?marker=waypoints:x:28.26,y:-25.80&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Key

4 Optional parameters

4.1 Width&Height (default = 640 and 480)

The size of the map image is determined by the width and the height parameters. Both parameters are optional and if missing, will default to width=640 and height=480.

For example, a half size map:
https://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&width=320&height=240&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.

width

4.2 Map type (default = map)

The map image can be a normal, stylised map showing roads and areas (map), satellite, aerial imagery (maptype=imagery) or a combination of the two (maptype=hybrid) or traffic map (maptype=traffic). The default, if this optional parameter is missing, is maptype=map.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&maptype=map&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Map type: MAP
mapst
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&maptype=imagery&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Map type: IMAGERY
mandatory_param2

http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&maptype=hybrid&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.

Map type: HYBRID
Hybrid
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&maptype=traffic&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Map type: TRAFFIC

trafficccc

4.3 Image format (default = png)

The map image format can be PNG or JPEG. The default format, if this optional parameter is missing, is imageformat=png.

For each format, a quality parameter can be specified:

  • &quality= (0 = worst /100 = best)(default =50 percent)
For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&imageformat=jpeg&quality=80&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
mapst

5 Additional parameters

5.1 Marker

The marker parameter is composed of a number of semicolon-separated optional attributes followed by a waypoints attribute (with one or more positions separated by the pipe (‘|’) character). Marker attributes either relate to Built-in styles or Custom icons. The Built-in attributes can be:

  • style: (pin (default), bigpin, or, in the future, smallpin, button, …);
  • colour: (red (default), orange, yellow, green, blue, purple, black, white);
  • startLabel: (A..Z, 0..25) (default = blank);
  • waypoints: position1|postion2|…
The position can be in address format or longitude, latitude.

If attributes are not parsable, default attributes will be used.

If the startLabel is not blank, the label will be incremented by one for each marker placed.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&marker=style:pin;colour:green;startlabel:A;waypoints:446+Rigel+Ave,Pretoria|x:28.26,y:-25.80|Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Mapmarkers

It is possible to have multiple marker parameters, if different styles are required.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&marker=colour:yellow;waypoints:446+Rigel+Ave,Pretoria&marker=colour:green;startlabel:1;waypoints:x:28.26,y:-25.80|Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
MultiMarkers

The Custom icons marker attributes can be:

  • icon: The URL of the icon image (ampersand encoded as %26, semicolon as %3B);
  • h_offset: (default = 0);
  • v_offset: (default = 0);
  • waypoints: position1|postion2|…
  • forceIconFetch:true;
Because the icon attribute is separated from the next attribute or the waypoints attribute by a semicolon, and because the parameters are separated from each other by an ampersand, if a semicolon or an ampersand occurs in the image URL it must be replaced by the URL-encoded format: %3B and %26 respectively. The h_offset and v_offsetrefer to the anchor point of the icon, relative to the top left corner of the icon. No labelling is possible with Custom icons and Custom icons will not increment the labelling of Built-in markers. Built-in markers can be mixed with Custom icon markers. If a Custom icon cannot be retrieved, it will be replaced with the default Built-in marker.
The Custom icon will be cached on the server to reduce map generation time and unnecessary icon fetches. If, however, the icon changes, the attribute forceIconFetch:true can be used once to update the server’s cached copy, but this fetch incurs a 20 second penalty, so should not be repeated unnecessarily.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&marker=icon:http://maps.afrigis.co.za/Images/Pin_Red_32x32_24bit.png;v_offset:-32;h_offset:-5;waypoints:446+Rigel+Ave,Pretoria&marker=style:bigpin;colour:green;startlabel:Z;waypoints:x:28.26,y:-25.80^Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
LabeledMarker

Note, in the above URL, the first Built-in marker is labelled Z but the second one is not labelled at all because no character logically follows Z. Similarly, 25 is the upper limit for number labels.

If neither style nor icon are specified, or both style and icon are specified, style will be assumed.

5.2 Polyline

The polyline parameter is composed of a number of semicolon-separated optional attributes followed by a waypoints attribute (with two or more positions separated by the pipe (‘|’) character). The attributes can be:

  • strokeColour: (red (default), orange, yellow, green, blue, purple, black, white or a more comprehensive list of 140 ‘KnownColors’ (see Appendix A – ‘KnownColors’));
  • strokeWidth: (0 to 20) (default = 2);
  • strokeOpacity: (0 to 100) (default = 100 percent);
  • waypoints: position1|postion2|…
The positions can be in address format or longitude, latitude.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&polyline=waypoints:446+Rigel+Ave,Pretoria|x:28.26,y:-25.80|Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.

It is possible to have multiple polyline parameters.
Polyline

5.3 Polygon

The polygon parameter is composed of a number of semicolon-separated optional attributes followed by a waypoints attribute (with three or more positions separated by the pipe (‘|’) character). The attributes can be:

  • strokeColour: (red (default), orange, yellow, green, blue, purple, black, white or a more comprehensive list of 140 ‘KnownColors’ (see Appendix A – ‘KnownColors’));
  • strokeWidth: (0 to 20) (default = 2);
  • strokeOpacity: (0 to 100) (default = 100 percent);
  • fillColour: (red (default), orange, yellow, green, blue, purple, black, white or a more comprehensive list of 140 ‘KnownColors’ (see Appendix A – ‘KnownColors’));
  • fillOpacity: (0 to 100) (default = 50 percent);
  • waypoints: position1|postion2|position3|…
The positions can be in address format or longitude, latitude.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&polygon=fillcolour:orange;waypoints:446+Rigel+Ave,Pretoria|x:28.26,y:-25.80|Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Polygon

The polygon will automatically be completed, it is not necessary to repeat the first position at the end of the list. It is possible to have multiple polygon parameters.

5.4 Directions

The directions parameter is composed of a number of semicolon-separated optional attributes followed by a waypoints attribute (with two or more positions separated by the pipe (‘|’) character). The attributes can be:

  • strokeColour: (red (default), orange, yellow, green, blue, purple, black, white or a more comprehensive list of 140 ‘KnownColors’ (see Appendix A – ‘KnownColors’));
  • strokeWidth: (0 to 20) (default = 2);
  • strokeOpacity: (0 to 100) (default = 100 percent);
  • route: (time, distance) (default = time) ;
  • avoid: (highway, toll) (default = none) ;
  • withEndpoints: (true, false) (default = true) ;
  • waypoints: position1|postion2|…
The positions can be in address format or longitude, latitude.

There can be multiple avoid attributes, but only one of the others where it calls for a choice to be made.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&directions=withEndpoints:false;avoid:highway;avoid:toll;waypoints:446+Rigel+Ave,Pretoria|x:28.26,y:-25.80|Menlyn+Park+Shopping+Centre,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Directions

5.5 Caption

The caption parameter is composed of a number of semicolon-separated optional attributes followed by a waypoints attribute (with one or more positions separated by the pipe (‘|’) character). The attributes can be:

  • text: The text to be displayed on the map (ampersand encoded as %26, semicolon as %3B);
  • font: (Microsoft San Serif (default), or a comprehensive list of ‘ASP.NET fonts’ (see appendix B));
  • size: (5 to 30 (default = 10));
  • align: (left, right, centre, above (default), below); defines the caption’s anchor point, by default, the caption will appear above the waypoint.
  • h_offset: (default = 0); offset in pixels
  • v_offset: (default = 0); offset in pixels
  • textColour: (red, orange, yellow, green, blue, purple, black (default), white or, a more comprehensive list of 140 ‘KnownColors’ (see appendix A));
  • borderColour: (none, red, orange, yellow, green, blue, purple, black (default), white or, a more comprehensive list of 140 ‘KnownColors’ (see appendix A));
  • fillColour: (none, red, orange, yellow, green, blue, purple, black, white (default) or, a more comprehensive list of 140 ‘KnownColors’ (see appendix A))
  • waypoints: position1|postion2|…

The positions can be in address format or longitude, latitude.

For example:
http://api.afrigis.co.za/StaticMap/?centre=446+Rigel+Ave,Pretoria&zoom=12&caption=text:AfriGIS+Office;borderColour:none;fillColour:none;align:top;v_offset:10;waypoints:446+Rigel+Ave,Pretoria&key=[YOUR_KEY]/trial
For information on how to calculate the authentication code, please visit the Static Maps Authentication page.
Caption

Project Details