.NET API

Mapzania.Services Class

The Mapzania.Services class is the primary entry point for setting up and configuring Mapzania .NET services. It is a static class and accessed using the methods listed below.

Static Methods

RegisterLogger

This method allows the user to add a logger to Mapzania for a preferred logging platform (e.g. NLog or log4net).

NOTE: This method can be called multiple times, should you want to register more than one logger class.

Mapzania generates a number of logs namely:

  • Error Log - Exceptions are logged to this log
  • Debug Log - Detailed debugging information is logged to this log
  • Message Log - Messages relating to service events are logged to this log
  • Custom Logs - A number of custom events are logged to these logs. These include events such as WebApi calls, Metrics and Usage.

NOTE: See Adding Logging Services for an example of a logger implementation.

Parameters

Name Required Type Description
logger Yes Mapzania.Logging.ILogger The concrete implementation of a logger created by the user.

Example


public class MvcApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        var logPath = @"c:\logs";
        var logger = new NLogLogger(logPath);
        Mapzania.Services.RegisterLogger(logger);

        var logger2 = new Log4NetLogger();
        Mapzania.Services.RegisterLogger(logger2);
    
        Mapzania.Services.Start(this);
    
        AreaRegistration.RegisterAllAreas();
    
        GlobalConfiguration.Configure(WebApiConfig.Register);
    
        RouteConfig.RegisterRoutes(RouteTable.Routes);
        BundleConfig.RegisterBundles(BundleTable.Bundles);
    }
}

RegisterMapboxLayerSource

This method is used to register a single Mapbox layer-source.

To use Mapbox tile-sets as background layers-sources, you need to create an account on the Mapbox website. You will then have access to all the standard Mapbox tile-sets in addition to having the ability to create your own tilesets.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to Mapbox.

Parameters

Name Required Type Description
key Yes String This is the layer-source key that will be used to identify the Mapbox layer.
options Yes Mapzania.Platform.Mapbox.LayerSourceOptions Options for registering the layer-source (see below for more details).

Options

Name Default Required Type Description
MapId null Yes String The Mapbox Map Id for example 'mapbox.satellite'.
AccessToken null Yes String The Mapbox Access Token that is provided to you when you register on their site.

Example


void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the Mapbox layer-source
    var options = new Platform.Mapbox.LayerSourceOptions {
        MapId = "mapbox.satellite",
        AccessToken = "[Your Mapbox Access Token]"
    }
    
    // Register the Mapbox layer-source
    Mapzania.Services.RegisterMapboxLayerSource("MAPBOX_SATELLITE", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterMsSqlSpatialDatabase

This method is used to register all spatial tables in an MSSQL Spatial database as layer-sources.

Parameters

Name Required Type Description
connectionString Yes String The connection-string to the database
options No Mapzania.Platform.MsSqlSpatial.ProviderOptions Options for registering the database.

Options

Name Default Type Description
Prefix String.Empty String This string is appended to the spatial table name to provide the layer-source key (which is always uppercase). For example if the spatial table in the database is named "AmericanRivers" and the prefix is set to "USA_" the layer-source key will be "USA_AMERICARIVERS"
DefaultSRID "LATLONG" String Sets the SRID of all layer-sources registered from the database
DefaultIdColumnName "Id" String Sets the id column name for all layer-sources registered from the database
DefaultGeometryColumnName "Geometry" String Sets the geometry column name for all layer-sources registered from the database

Example


void Application_Start(object sender, EventArgs e)
{
	...

    // Obtain a connectionstring from ConfigurationManager (web.config)
    var connectionString = ConfigurationManager.ConnectionStrings["MY_CONNECTION"].ConnectionString;
    
    // Set options for MSSQL Spatial LayerSources
    var options = new Platform.MsSqlSpatial.ProviderOptions {
        Prefix = "MYDB_",
        DefaultSRID = "EPSG:4283",
        DefaultIdColumnName = "MY_ID",
        DefaultGeometryColumnName = "MY_GEOMETRY"
    };
    
    // Register the MSSQl Spatial database
    Mapzania.Services.RegisterMsSqlSpatialDatabase(connectionString, options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterPostGISDatabase

This method is used to register all spatial tables in an PostGIS database as layer-sources.

Parameters

Name Required Type Description
connectionString Yes String The connection-string to the database
options No Mapzania.Platform.PostGIS.ProviderOptions Options for registering the database.

Options

Name Default Type Description
Prefix String.Empty String This string is appended to the spatial table name to provide the layer-source key (which is always uppercase). For example if the spatial table in the database is named "AmericanRivers" and the prefix is set to "USA_" the layer-source key will be "USA_AMERICARIVERS"
DefaultSRID "LATLONG" String Sets the SRID of all layer-sources registered from the database

Example


void Application_Start(object sender, EventArgs e)
{
	...

    // Obtain a connectionstring from ConfigurationManager (web.config)
    var connectionString = ConfigurationManager.ConnectionStrings["MY_CONNECTION"].ConnectionString;
    
    // Set options for PostGISl LayerSources
    var options = new Platform.PosGIS.ProviderOptions {
        Prefix = "MYDB_",
        DefaultSRID = "EPSG:4283"
    };
    
    // Register the PostGIS database
    Mapzania.Services.RegisterPostGisDatabase(connectionString, options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterRoutes

The purpose of this method is to register the WebApi routes of the REST API and its controllers with your application. These endpoints are used by the JavaScript API for map interactions.

NOTE: This method must be called to activate Mapzania properly. Also, it is vital that you place this line after config.MapHttpAttributeRoutes() and before you define your default route with config.Routes.MapHttpRoute, otherwise the Mapzania endpoints may not initialize correctly.

Parameters

Name Required Type Description
config Yes System.Web.Http.HttpConfiguration The configuration object of the web server instance.
options No Mapzania.RouteOptions Options for route registration.

Options

Name Default Type Description
ApiRootUrl "mz" String This will set the root URL for the Mapzania REST API to a custom URL.

Examples

MVC Only

global.asax

protected void Application_Start()
{
    // Start Mapzania
	Mapzania.Services.Start(this);

    AreaRegistration.RegisterAllAreas();
    FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);

    //Register Mapzania Routes (endpoints)
    Mapzania.Services.RegisterRoutes(GlobalConfiguration.Configuration, new RouteOptions {
        ApiRootUrl="api/mapzania/1.0/"
    });

    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
}
WebApi

WebApiConfig.cs (or equivalent)

public static void Register(HttpConfiguration config)
{
	config.MapHttpAttributeRoutes();

    //Register Mapzania Routes (endpoints)
    Mapzania.Services.RegisterRoutes(config, new RouteOptions {
        ApiRootUrl="map_api/1.0/"
    });

    config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
    );
}

RegisterTomTomMapLayerSource

This method is used to register a single TomTom Online Map layer-source.

To use TomTom layers as background layers-sources, you need to create an account on the TomTom Developer Site.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to TomTom.

Parameters

Name Required Type Description
key Yes String This is the layer-source key that will be used to identify the TomTom layer.
options Yes Mapzania.Platform.TomTom.MapLayerSourceOptions Options for registering the layer-source (see below for more details).

Options

The options in the table below are described in more detail in the TomTom Online Maps documentation.

Name Default Required Type Description
ApiKey null Yes String The API Key provided to you when you register with TomTom.
Layer LayerEnum.Basic No LayerEnum The layer of the tiles to be rendered.
Style StyleEnum.Main No StyleEnum The style of the tiles to be rendered.
View ViewEnum.Unified No ViewEnum The Geopolitical view of the tiles.
Language "NGT" No String The language to be used in tile labels.

Example


void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the TomTom layer-source
    var options = new Platform.TomTom.MapLayerSourceOptions {
        ApiKey = "[Your TomTom API Key]",
        Layer = Platform.TomTom.MapLayerSourceOptions.LayerEnum.Basic,
        Style = Platform.TomTom.MapLayerSourceOptions.StyleEnum.Night,
        View = "NGT",
        Language = "fr-FR"        
    }
    
    // Register the TomTom layer-source
    Mapzania.Services.RegisterTomTomMapLayerSource("TOMTOM_TILES_NIGHT", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterTomTomTrafficFlowLayerSource

This method is used to register a single TomTom Online Traffic traffic-flow layer-source.

To use TomTom layers as background layers-sources, you need to create an account on the TomTom Developer Site.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to TomTom.

Parameters

Name Required Type Description
key Yes String This is the layer-source key that will be used to identify the TomTom layer.
options Yes Mapzania.Platform.TomTom.TrafficFlowLayerSourceOptions Options for registering the layer-source (see below for more details).

Options

The options in the table below are described in more detail in the TomTom Online Traffic Flow documentation.

Name Default Required Type Description
ApiKey null Yes String The API Key provided to you when you register with TomTom.
Style StyleEnum.Absolute No StyleEnum The style of the tiles to be rendered.
Thickness 10 No Integer32 The thickness of the traffic flows (1-20).

Example


void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the TomTom layer-source
    var options = new Platform.TomTom.TrafficFlowLayerSourceOptions {
        ApiKey = "[Your TomTom API Key]",
        Style = Platform.TomTom.TrafficFlowLayerSourceOptions.StyleEnum.Absolute,
        Thickness = 15
    }
    
    // Register the TomTom layer-source
    Mapzania.Services.RegisterTomTomTrafficFlowLayerSource("TOMTOM_FLOWS", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterTomTomTrafficIncidentsLayerSource

This method is used to register a single TomTom Online Traffic traffic-incidents layer-source.

To use TomTom layers as background layers-sources, you need to create an account on the TomTom Developer Site.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to TomTom.

Parameters

Name Required Type Description
key Yes String This is the layer-source key that will be used to identify the TomTom layer.
options Yes Mapzania.Platform.TomTom.TrafficIncidentsLayerSourceOptions Options for registering the layer-source (see below for more details).

Options

The options in the table below are described in more detail in the TomTom Online Traffic Incidents documentation.

Name Default Required Type Description
ApiKey null Yes String The API Key provided to you when you register with TomTom.
Style StyleEnum.S1 No StyleEnum The style of the tiles to be rendered.

Example


void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the TomTom layer-source
    var options = new Platform.TomTom.TrafficIncidentsLayerSourceOptions {
        ApiKey = "[Your TomTom API Key]",
        Style = Platform.TomTom.TrafficIncidentsLayerSourceOptions.StyleEnum.S3
    }
    
    // Register the TomTom layer-source
    Mapzania.Services.RegisterTomTomTrafficIncidentsLayerSource("TOMTOM_TRAFFIC", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

Start

Starts Mapzania services such as layer-source detection, logging, license-validation and endpoint-activation.

Parameters

Name Required Type Description
app Yes System.Web.Http.HttpConfiguration The configuration object of the web server instance.
options No Mapzania.Options Options for start-up.

Options

Name Default Type Description
LicenseKey String.Empty String The license key of your installation of Mapzania.
You can obtain licenses here.
MapStylerAccess AllowLocal Mapzania.Access An enum that sets the web visibility of the MapStyler.

Valid values are:
- AllowNone (MapStyler is disabled)
-AllowLocal (MapStyler can be run on local machine)
-AllowAll (MapStyler can be run from any machine)
ServicesAccess AllowLocal Mapzania.Access An enum that sets the web visibility of the ROOT/services endpoints in the REST API.

Valid values are:
- AllowNone (endpoints are disabled)
-AllowLocal (endpoints can be accessed on local machine)
-AllowAll (endpoints can be accessed from any machine)

Example

void Application_Start(object sender, EventArgs e)
{
	...
    // Start Mapzania 
    Mapzania.Services.Start(this, new Options {
        MapStylerAccess = Access.AllowLocal,
        ServicesAccess = Access.AllowNone,
        LicenseKey = "<add licence key here>"        
    });

    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}