Maprosoft API Reference

Page Contents

Introduction

The data added to Maprosoft can be presented in numerous ways. Administrators use the Map Builder Control Panel to generate HTML code and/or URLs that result in pages presenting information as desired. This API supplements this technique of page generation since it documents the various options and allows them to be combined either manually or using third party tools such a Content management Systems (CMS).

In addition to page generation options, the API also provides various web services. These services provide various forms of information and interaction.

URLs

Since Maprosoft is a web application, it is accessed via a URL in the browser. The URL specifies the content that Maprosoft must generate and return to the browser. Here is an example breakdown of a URL for the purposes of this discussion:

  • https://www.maprosoft.com/appmap?enableDirections=no

There are three main parts to the URL:

  • First part (red): addresses a specific deployment of Maprosoft.
  • REST resource (blue): identifies the type of output required.
  • Parameters (green): options relating to the type of output required.

Parameter Types

Each parameter value in this API is of one of the following types:

Parameter TypeDefinition
StringAny UTF-8 encoded text.
BooleanPossible values: yes, no, true, false.
IntegerAny integer value.
DoubleAny decimal value.
Focus ActionPossible values: info-window, driving-directions, bicycling-directions, walking-directions, street-view.
View PositionPossible values: top, left, right, bottom.

Page Generation REST API

This section of the API identifies how to generate different types of pages from the data imported into Maprosoft. The Map Builder control panel within the administration application provides a user friendly way to create maps using various parameters and constants identified here. The documentation of these parameters and constants allows content management system vendors to provide similar functionality to the Map Builder control panel. It also allows web developers to gain a deeper understanding of how content can be built.

It should be noted that all parameters in this API are case sensistive.

Page Generation REST Resources

There are various REST resources corresponding to the different types of pages that can be generated:

Page TypeREST ResourceDescription
MapmapPages containing dynamically generated interactive maps.
Shared MapsharedPages containing pre-configured maps.
Mobile Appmobile-appAn interactive web application suitable for mobile devices.
AdminadminThe administration application.
AboutaboutProvides information about Maprosoft including the version that is running.
TexttextPages containing spatial information presented in textual form usually comprising links to dynamically generated maps.
Map Gallerymap-galleryPages containing a grid of image links representing different maps for each of the feature types.
Site MapsitemapProduces an XML sitemap that can be submitted to web spiders to crawl the content of the pages produced by Maprosoft.

Page Generation Parameters

The following table identifies the various parameters that can influence page generation.

Parameter NameTypeDescriptionDefault ValuePage Type(s)
addHeaderAndIntroduction Boolean This parameter is used to indicate whether the generated text page should include a header and introduction. no Text
allowIssueReporting Boolean This parameter indicates whether to enable the issue reporting functionality in the generated page. no Map
autoHideMapToolbar Boolean This parameter indicates whether the toolbar should be automatically hidden when the display is small. no Map
customLatitude Double This parameter identifies a custom initial map centre latitude. This will be ignored if zoomBasedOnExtent is set. 0.0 Map
customLongitude Double This parameter identifies a custom initial map centre longitude. This will be ignored if zoomBasedOnExtent is set. 0.0 Map
customZoom Double This parameter identifies a custom initial map zoom value. This will be ignored if zoomBasedOnExtent is set. 0.0 Map
downloadFeatures String This parameter identifies features to be downloaded and made visible automatically. A single feature is identified by its feature type name and external key separated by --. Multiple features can be specified by adding multiple mappings as per the following example:
&downloadFeatures=Council%20Developments--Central%20Park&downloadFeatures=Shopping--Queen%20Victoria%20Building
null Map
enableDirections Boolean This parameter identifies whether directions functionality should be enabled. yes Map
featureListViewPosition View Position If showFeatureDetailsPanel is set, this parameter identifies its position (top, left, right or bottom). bottom Map
featureListViewSize Integer If showFeatureDetailsPanel is set, this parameter identifies its size in pixels. 300 Map
featureSelectors String This parameter allows features to be filtered based on a key/value pair.Where the key/value expression identifies equality, the key and value should be separated by --. Where the key/value expression identifies inequality, the key and value should be separated by !-. This allows features to be selected based on their types, but filtered by certain criteria. Multiple key/value pairs can be specified whereby each pair is separator by __. For example, all open development applications not in the suburb of Sydney could be specified with the selector as 'Status--Open__Suburb!-Sydney'. (none) Text
featureWidth String This parameter is used to identify the width of each feature grid item. This is applicable when the listing layout type is grid. Text
focusAction Focus Action This parameter is used to identify the type of action required when focussing on a feature. Allowed values are info-window, driving-directions, bicycling-directions, walking-directions, street-view and tour. info-window Map
focusDelay Integer This parameter is used to identify the delay in seconds prior to performing a focusAction. 0 Map
focusFeature String This parameter identifies a feature to be initially focussed. The type of focus is determined by focusAction. The value should be the feature type name and the feature's key separated by --. A non-URL encoded example is 'Glebe Library--12'. In this example, 12 is the key of the feature as identified when the features of this type were imported. Refer to [Map Data Introduction] for more information about feature keys. null Map
fullPage Boolean This parameter is used to indicate whether Maprosoft should generate a standalone web page.Set to false when the output is to be included within a DIV. yes Text
fullscreenEnabled Boolean This parameter indicates whether to enable a control allowing fullscreen. yes Map
highlightAreaOfInterest Boolean This parameter indicates whether to highlight the area of interest. yes Map
initialPlaceName String Identification of the initial place that the application should display. For the admin application, this is the name of a control panel. For the mobile app, this is the name of one of the mobile app views. null Admin, Mobile App
itemsPerPage Integer This parameter is used to identify the page size when querying features in a paged manner. 100 Text
listingLayoutType String This parameter is used to identify the type of textual layout required. Tabular Text
mapApi String This parameter identifies the map system to use. Use GoogleMaps for the Google Maps API and MapQuest for MapQuest. GoogleMaps Map
mapLayout String This parameter identifies the map layout to use. Possible options are standard and mobile-header. standard Map
northEastLatitude Double This parameter identifies the initial north east latitude of the map (used if zoomBasedOnExtent is set). 0.0 Map
northEastLongitude Double This parameter identifies the initial north east longitude of the map (used if zoomBasedOnExtent is set). 0.0 Map
pageNumber Integer This parameter is used to identify the page number when querying features in a paged manner. 1 Text
parameterBuilderShowCodeSection Boolean This parameter is used to hide the generated code section of the map builder control panel. yes Admin
parameterBuilderShowPreviewSection Boolean This parameter is used to hide the preview section of the map builder control panel. yes Admin
resizeMapFrame Boolean This parameter is used to indicate whether the frame containing the generated text should be resized according to its content. yes Text
showAddressSearchControl Boolean This parameter can be used to indicate whether a control should be displayed which will allow addresses to be entered and then used to display information for. no Map
showAllFeatureTypes Boolean This parameter indicates whether all types of features should be exposed to the user. If the map toolbar is visible, then selecting this option will result in controls that allow the user to control the visibility of features of each feature type. If the map toolbar is not visible, then selecting this option will result in all features being automatically downloaded. If choosing not to display the map toolbar, then this options should be used with caution when there are a large number of feature types with many features, otherwise too many features will be downloaded. yes Map
showFeatureDetailsPanel Boolean This parameter indicates whether to show a view displaying feature details. no Map
showFeatureTypes String This parameter identifies the types of features to display automatically. If the map toolbar is visible and there are multiple feature type specified, then the feature types will listed so that the user can control when the features are downloaded. If the map toolbar is visible and there is only one feature type specified, then all features of the feature type are downloaded and displayed automatically. If the map toolbar is not visible, then all features of the specified feature types will downloaded and displayed automatically. The value should be a list of feature type names separated by __. null Map
showMapToolbar Boolean This parameter indicates whether a toolbar should be displayed allowing the control of feature visibility and other functions. yes Map
showPanAndZoonAllDataButton Boolean This parameter indicates whether to show a control on the toolbar allowing the map to be panned and zoomed such that all features are visible. no Map
showPanAndZoonToInitialSettingsButton Boolean This parameter indicates whether to show a control on the toolbar allowing the map to be panned and zoomed to its initial settings. no Map
showPanAndZoonVisibleDataButton Boolean This parameter indicates whether to show a control on the toolbar allowing the map to be panned and zoomed such that all visible features are in view. no Map
showRulerControl Boolean This parameter indicates whether to show a ruler control on the toolbar. no Map
showSearchControl Boolean This parameter indicates whether to show a search control on the toolbar. no Map
showStackToolbar Boolean This parameter indicates which form of toolbar to show - a plain toolbar or one divided into sections and acts like a stack. yes Map
showTextSearchControl Boolean This parameter can be used to indicate whether a control should be displayed providing text search functionality. no Map
southWestLatitude Double This parameter identifies the initial south west latitude of the map (used if zoomBasedOnExtent is set). 0.0 Map
southWestLongitude Double This parameter identifies the initial south west longitude of the map (used if zoomBasedOnExtent is set). 0.0 Map
team String This parameter identifies your team. This is required where there is no logon required such as publicly available maps. null Map, About, Map Gallery, Mobile App, Text
toolbarSectionsExplicitVisibilities String This parameter specifies the sections of the map toolbar that should be visible. If this parameter is not provided, then the visibilities will be determined by the functionality enabled and default values. Multiple toolbar sections can be specified by separating their names by --. Here is an example example:
Information--Search--Issues
null Map
zoomBasedOnExtent Boolean This parameter indicates whether to set the initial zoom of the map such that a specified range of locations will be visible. If this is set, then values for southWestLatitude, southWestLongitude, northEastLatitude and northEastLongitude must be provided. This will override any value set for customZoom. no Map
zoomToFeatures Boolean This parameter indicates whether to adjust the initial zoom of the map to the extent of the initially downloaded features. This setting will override other zoom related settings such as zoomBasedOnExtent. yes Map

Page Generation Constants

The following predefined API values can be used.

ConstantTypeDescriptionPage Type(s)
!- String This is the separator required between key/value pairs to specify inequality. Text
-- String This is the separator required between feature type names and feature keys such that a unique feature can be identified. For more information about feature keys, please see the Map Data Overview page. For example, this is used by the focusFeature parameter. Map
-- String This is the separator required between key/value pairs to specify equality. Text
__ String This is the separator required between feature types identified by showFeatureTypes. Map
__ String This is the separator required to specify multiple key/value pairs. Text
bicycling-directions String Setting focusAction to this value results in bicycling directions to the feature being displayed. Map
driving-directions String Setting focusAction to this value results in driving directions to the feature being displayed. Map
GoogleMaps String This value is used to identify the Google Maps API. Map
Grid String Setting listingLayoutType to this value results in grid layout format. Text
info-window String Setting focusAction to this value results in the feature's info window being opened. Map
MapQuest String This value is used to identify the MapQuest API. Map
mobile-header String This value is used to specify the map layout should account for a mobile device header. For example, when embedding the map in an iOS app, a header may exist showing such things as the time and the device's battery status. Map
standard String This value is used to specify the standardmap layout should be used. Map
street-view String Setting focusAction to this value results in a street view of this feature being displayed. Map
Tabular String Setting listingLayoutType to this value results in table layout format. Text
tour String Setting focusAction to this value results in a virtual tour of this feature. Map
walking-directions String Setting focusAction to this value results in walking directions to the feature being displayed. Map


Page Generation Examples


Example Maps:

A map showing one type of feature:

http://www.maprosoft.com/app/map?showAllFeatureTypes=no&showFeatureTypes=Parks&showMapToolbar=no

A map showing multiple types of features:

http://www.maprosoft.com/app/map?showAllFeatureTypes=no&showFeatureTypes=Railways__Train+Stations__Car+Parks__Cycle+Ways&showMapToolbar=no

A map showing driving directions to a specific feature 5 seconds after the map loads:

http://www.maprosoft.com/app/map?focusAction=driving-directions&focusDelay=5&focusFeature=Hospitals--504378750&showAllFeatureTypes=no&showMapToolbar=no


Tabular Output:

A standalone page containing a grid of one type of feature:

http://www.maprosoft.com/app/text?featureWidth=280px&fullPage=yes&listingLayoutType=Grid&resizeMapFrame=yes&showAllFeatureTypes=no&showFeatureTypes=Parks

Embeddable HTML containing a table of one type of feature (page 2, 5 items per page):

http://www.maprosoft.com/app/text?fullPage=no&itemsPerPage=5&listingLayoutType=Tabular&pageNumber=2&showAllFeatureTypes=no&showFeatureTypes=Parks


Mobile App:

The mobile app:

http://www.maprosoft.com/app/mobile-app


Map Gallery:

The map gallery:

http://www.maprosoft.com/app/map-gallery



Javascript postMessage API

This section of the API identifies how to interact with Maprosoft using Javascript. Maprosoft content is most often served in <iframe>s. For this reason, the Javascript API is based on Javascript's postMessage function. This provides a safe way to interact between browser windows and frames.

When Maprosoft receives a postMessage command, it first checks the where the call came from. More specifically, it checks the postMessage event's source value which identifies the team of the sender. If the team is different to the team of Maprosoft, then an extra check is made to ensure the source team is trusted. This extra check involves checking that the administrator has enabled CORS (see http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) and has identified the source team as being trusted. The administrator does this using the Security Control Panel.

Javascript postMessage Commands

The following table identifies the various commands supported by the Javascript postMessage API.

CommandDescription
addPinAdds a pin to the map. Responses may be returned by this command, however, the data attribute of the response will be empty.
featureSearchSearches for a feature and, if found, identifies it by opening an info window on it. Responses may be returned by this command, however, the data attribute of the response will be empty.

Javascript postMessage Parameters

The following table identifies the various parameters relating to the Javascript postMessage API.

Parameter NameTypeDescriptionDefault ValuePage Type(s)
address String This parameter is used to provide an address. For example: '35 Foo St, Bar'. null Map
command String This parameter identifies the type of post message command. null Map
data String This parameter is used in responses to return data. For example: 'Some Suburb'. null Map
errorHtml String This parameter is used in responses to provide details about any error that may have occurred. For example: 'No features were found at that address'. null Map
featureTypeName String This parameter is used to provide a feature type name. For example: 'Suburbs'. null Map
focusAction Focus Action This parameter is used to identify the type of action required when focussing on a feature. info-window Map
job String This parameter can be used by the caller to identify a command. When a job is provided, Maprosoft will send a response to the sender with the same job identified so that the client can associate which job the response corresponds to. This parameter is optional in requests to Maprosoft. For example: '1234'. null Map
latitude Double This parameter is used to provide a latitude value. For example: '-33.88'. 0.0 Map
longitude Double This parameter is used to provide a longitude value. For example: '151.19'. 0.0 Map
success Boolean This parameter is used in responses to indicate if the request was successful. For example: 'true'. no Map
title String This parameter is used to provide a title. For example: 'My House'. null Map

Javascript postMessage Examples


Add a Pin:

The following example will add a pin to the map at a specified geographic location:

mapFrame.postMessage('{"command": "addPin", "title": "My House", "latitude": "-33.88", "longitude": "151.19"}', "https://www.maprosoft.com/app")

Searching for a feature:

The following example will search for the suburb matching an address. If found, the suburb will be identified by opening its info window. Since a job is provided, Maprosoft will send a response to the sender.

mapFrame.postMessage('{"command": "featureSearch", "job": "1234", "featureTypeName": "Suburbs", "address": "126 Sophia St, Surry Hills", "focusAction": "OPEN_INFO_WINDOW"}', "https://www.maprosoft.com/app")



Services REST API

This section of the API identifies various services provided by Maprosoft. These services can be used in various ways such as to develop mobile applications.

API Keys

All Maprosoft services require a mandatory parameter identifying the API key. To obtain your API key, please contact us.


Summary of Services


Service NameDescription
Configuration Settings This service provides configuration information.
Issue/Problem Types This service provides the issue/problem types that have been defined.
Area of Interest This service determines if a point is within the area of interest.
Shadow Shape This service provides geographic shape information allowing shadow zones to be drawn so that the area of interest is highlighted. If the points in the polygon are ordered in an anti-clockwise direction, then it represents a hole in one of the other polygons.
Image Upload This service allows images to be uploaded as part of reporting problems.
Issue Report This service allows an issue/problem to be reported.

Configuration Settings

This service provides configuration information.

REST Resource:config
HTTP Method(s):GET and POST

Parameters:


NameTypeDescription
APIKey String Your API key.

Response (Key/Value Pairs):

The following configuration values are returned:

KeyTypeDescription
InitialLatitudeDoubleThe default initial centre latitude (centre of the area of interest).
InitialLongitudeDoubleThe default initial centre longitude (centre of the area of interest).
InitialZoomDoubleThe default initial map zoom (Google Maps zoom scale).
MinZoomDoubleThe minimum map zoom (Google Maps zoom scale)

Example Request:

http://www.maprosoft.com/app/config?APIKey=dUFxepwNf5n69o1Yy%2F6ZTMGUrOFukHCd

Example Response

InitialLatitude=-33.5
InitialLongitude=151.3
InitialZoom=11
MinZoom=7

Issue/Problem Types

This service provides the issue/problem types that have been defined.

REST Resource:IssueTypes
HTTP Method(s):GET and POST

Parameters:


NameTypeDescription
APIKey String Your API key.

Response (Key/Value Pairs):

This service returns the following properties:

KeyTypeDescription
IssueTypeNamesStringThe issue type names separated by '__'.
ErrorMessageStringAn error message if an error occurred. This may be omitted if no errors occurred.

Example Request:

http://www.maprosoft.com/app/IssueTypes?APIKey=dUFxepwNf5n69o1Yy%2F6ZTMGUrOFukHCd

Example Response

IssueTypeNames=Graffiti__Garbage Bin__Dumped Rubbish__Street Cleaning
ErrorMessage=Some text describing the error that occurred.

Area of Interest

This service determines if a point is within the area of interest.

REST Resource:AreaOfInterest
HTTP Method(s):GET and POST

Parameters:


NameTypeDescription
APIKey String Your API key.
Latitude Double The latitude of the point to be validated.
Longitude Double The longitude of the point to be validated.

Response (Key/Value Pairs):

If the point provided was within the are of interest, then the same point is returned, otherwise the closest point on the area of interest boundary is returned.

KeyTypeDescription
LatitudeDoubleThe latitude of the closest point within the area of interest.
LongitudeDoubleThe longitude of the closest point within the area of interest.

Example Request:

http://www.maprosoft.com/app/AreaOfInterest?APIKey=dUFxepwNf5n69o1Yy%2F6ZTMGUrOFukHCd&Latitude=15&Longitude=-30

Example Response

Latitude=-33.5
Longitude=151.3

Shadow Shape

This service provides geographic shape information allowing shadow zones to be drawn so that the area of interest is highlighted. If the points in the polygon are ordered in an anti-clockwise direction, then it represents a hole in one of the other polygons.

REST Resource:ShadowShape
HTTP Method(s):GET and POST

Parameters:


NameTypeDescription
APIKey String Your API key.

Response (Key/Value Pairs):

KeyTypeDescription
ShadowShapeStringThis will be a single line of text containing a series of points that make up one or more polygons that are the shadow zones. The format of the line is '[polygon-1][polygon-2][polygon-3][...][polygon-n]'. The format of each polygon is 'point-1 point-2 point-3 ... point-n'. The format of each point is 'latitude,longitude,altitude'.
ErrorMessageStringAn error message if an error occurred. This may be omitted if no errors occurred.

Example Request:

http://www.maprosoft.com/app/ShadowShape?APIKey=dUFxepwNf5n69o1Yy%2F6ZTMGUrOFukHCd

Example Response

ShadowShape=[-33.5,151.5,0.0 -33.5,152.5,0.0 -34.5,152.5,0.0 -34.5,151.5,0.0 -33.5,151.5,0.0][-31.5,151.5,0.0 -31.5,152.5,0.0 -32.5,152.5,0.0 -32.5,151.5,0.0 -31.5,151.5,0.0]
ErrorMessage=Some text describing the error that occurred.

Image Upload

This service allows images to be uploaded as part of reporting problems.

REST Resource:ImageUploadServlet
HTTP Method(s):POST

Parameters:


NameTypeDescription
APIKey String Your API key.
imageData Double The image bytes.
imageId Double A key identifying the image to be uploaded. If this is a new image, then this may be an empty string. If this is included, this image will replace the previously uploaded image identified by this ID.

Response (Key/Value Pairs):

The response identifies the uploaded image:

KeyTypeDescription
imageIdIntegerThe ID of the uploaded image.
ErrorMessageStringAn error message if an error occurred. This may be omitted if no errors occurred.

Example Response

imageId=1234
ErrorMessage=Some text describing the error that occurred.

Issue Report

This service allows an issue/problem to be reported.

REST Resource:IssueReport
HTTP Method(s):GET and POST

Parameters:


NameTypeDescription
APIKey String Your API key.
ProblemType String The type of problem.
Latitude Double The latitude of the issue (if a location was provided).
Longitude Double The longitude of the issue (if a location was provided).
AddressLine1 String The first line of the address of the issue (if an address was provided).
AddressLine2 String The seconbd line of the address of the issue (if an address was provided).
AddressSuburb String The suburb of the issue (if an address was provided).
Description String A description of the issue.
PhotoImageId Integer The ID of a photo of the issue uploaded using the ImageUploadServlet service.
User-Name String The name of the person reporting the issue (if provided).
User-Phone String The phone number of the person reporting the issue (if provided).
User-Email String The email address of the person reporting the issue (if provided).
CheckForDuplicates Boolean An indication of whether a check for duplicate issues should be performed.

Response (Key/Value Pairs):

The response will be empty unless an error occurs. The error message may indicate duplicates were detected.

KeyTypeDescription
ErrorMessageStringAn error message if an error occurred. This may be omitted if no errors occurred.

Example Request:

http://www.maprosoft.com/app/IssueReport?APIKey=dUFxepwNf5n69o1Yy%2F6ZTMGUrOFukHCd&AddressLine1=Unit+5%2C+106+Perryman+Rd&AddressLine2=&AddressSuburb=Woolloomooloo&CheckForDuplicates=yes&Description=Some+rubbish+has+been+dumped+in+the+park.&Latitude=-33.5&Longitude=151.5&PhotoImageId=1234&ProblemType=Dumped+Rubbish&User-Email=fred%40somewhere.com&User-Name=Fred&User-Phone=61+2+1234+5678

Example Response

ErrorMessage=The issue type 'Dumped Rubbish' is no longer available for issue reporting.