Configuring the server

Use the following configuration files to manage authentication of clients with the GeoStream server, access to data files, and the types of overlay data that can be displayed on a GeoStream map.

• web.config
• FriendsFile
• AuthFile
• UserInfoFile
• RepositoryConfig
• TrafficConfig
• LayersConfig
• RedirectConfig
• GeoStreamConfig

The file web.config is included by default and contains the definitions for the remaining configuration files. For example, to add a UserInfoFile, add the following syntax into the web.config file (in this example, the UserInfoFile is named userinfo.config):

<appSettings>
...
<add key="UserInfoFile" value="userinfo.config" />
...
</appSettings>

The configuration files exist on the server side only, and are used to permit or restrict access to the server. By default these files are placed in the following directory:

• C:\Program Files\Telogis\GeoBase\GeoStream\server\

The following table lists the files to use when completing various GeoStream server configuration tasks.

Note
After you update the configuration files, you must restart the GeoStream website within IIS to apply the changes to the server environment. For details on configuring shared keys for trusted networks and load balancing, see the information about server key sharing .

This file holds the values for the authentication settings:

• AuthFile (for example key="AuthFile" value="users.config")

• FriendsFile (for example key="FriendsFile" value="friends.config")

• ServerKey (for example key="ServerKey" value="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

• MaxSessionLength (for example key="MaxSessionLength" value="7.00:00")

Note
The server key, a globally unique identifier (GUID), is used in the formation of the authentication token. Depending on client-server topography, the server key might be shared among other servers or clients. For details, see the information about server key sharing .

Enabling Legacy Map Style

If you want to revert all maps served by your GeoStream server to legacy map style used in pre-4.0 GeoBase releases, this can be done by setting the UseLegacyStyle key/value pair to true.

<appSettings>
...
<add key="UseLegacyStyle" value="true" />
...
</appSettings>

Alternatively, if you want to enable legacy tiles on an on-demand basis, then this can be done in one of two ways, depending on your target platform:

• JavaScript - set the useLegacyStyle constructor argument of the TileLayer Class [JavaScript] to true.
• .NET - set the Style property of your IMap object to MapStyleLegacyStyle. See Map Styles and Parameters for further information.

HTTP Compression

Optionally, you can also enable/disable HTTP compression (gzip and deflate algorithms are supported) using the CompressJSON key/value pair. If the value attribute of CompressJSON is set to true, then HTTP compression is enabled for JSON. If it is set to any other value, or omitted, then compression is not enabled.

The CompressJSON value attribute is an optional child element of the <appSettings> element, as shown in the example below.

<appSettings>
...
<add key="CompressJSON" value="true" />
...
</appSettings>

Note
The CompressJSON feature only affects JSON.

Decompression Cache Size

You can set the maximum size of the decompression cache, in megabytes, when using compressed GBFS map data, for example file_Z.gbfs). To do this, use the DecompressionCacheSizeMb key/value pair.

The default memory value is 1GB, but the use of more memory can improve performance on servers with greater available memory.

The DecompressionCacheSizeMb value attribute is an optional child element of the <appSettings> element, as shown in the example below.

<appSettings>
...
<add key="DecompressionCacheSizeMb" value="1024"/>
...
</appSettings>

Serving Tiles without Authentication

If the Web.config key EnableTilesWithoutAuth is set to true, then no authentication is required for requests to tile.aspx, provided those requests include valid dataset and dataset hash parameters (data and dsh respectively) in the URL string. This configuration can be used in the JavaScript client to allow the serving of tiles without using either a cookie or including the authentication token in request URLs, which can improve browser caching performance in environments where third-party cookies are restricted.

<appSettings>
...
<add key="EnableTilesWithoutAuth" value="true"/>
...
</appSettings>

In the JavaScript client, set the TileLayer Class [JavaScript] config argument suppressAuthToken to true. This setting completes initial authentication to gain a valid data hash, then continues the session without using a cookie if permitted, or without if these are restricted.

var map = new Map({id: 'main_map', tileLayerConfig: {suppressAuthToken: true}});

Note that this functionality does not work if suppressTileHashes is set to true in the TileLayer Class [JavaScript] tileConfig argument.

Logging exceptions

To log all GeoStream exceptions, insert the following key:

<appSettings>
...
<add key="ExceptionLogging" value="true"/>
...
</appSettings>

When logging has been enabled, a text format log (.log extension) is be stored in the Logs sub-folder of the GeoStreamData folder (located in C:\ProgramData\GeoStreamData in a default server installation). Exception log files are named using the format geostreamExceptions_yyMMdd_hhmmss.log.

Individual log entries are formatted as follows:

<LOG DIRECTION> <TIME STAMP> - <MESSAGE>

1. LOG DIRECTION. This indicates the direction of the log. Typically, the value is set to '----', indicating no direction. The direction can also be '>>>>' for logs that are being sent, or '<<<<' for logs that are being received

2. TIME STAMP. The date and time of the log entry in UTC format

3. MESSAGE. The content of the log message

Logging geocoding requests

To log all GeoStream geocoding requests, insert the following key:

<appSettings>
...
<add key="GeocodingLogging" value="true"/>
...
</appSettings>

When logging has been enabled, a text format log (.log extension) is stored in the Logs sub-folder of the GeoStreamData folder (located in C:\ProgramData\GeoStreamData in a default server installation). Geocoding log files are named using the format geocoding_yyMMdd_hhmmss.log.

Individual log entries are formatted in the same way as the GeoStream exception logs described above:

<LOG DIRECTION> <TIME STAMP> - <MESSAGE>

Specifying a route memory limit

To specify a limit on the memory available for routing calculations, insert the following key:

<appSettings>
...
<add key="RoutingMemoryLimit" value="10"/>
...
</appSettings>

This key specifies the memory in megabytes that can be used. In the example above, the GeoStream server can use a maximum of 10MB when calculating routes.

Canceling slow routes

You can specify a time limit for route calculations, and the proportion of the time limit that should be used for calculating a route before interrupting the calculation and returning the best available route in the remaining time. To do this, insert the following keys:

<appSettings>
...
<add key="RoutingTimeLimit" value="60"/>
<add key="RoutingSoftTimeoutFraction" value="0.8"/>
...
</appSettings>

In the example above, the GeoStream server will attempt to return the route processed so far after 0.8 of 60 seconds (that is 48 seconds) and, if the result preparation does not finish in the remaining 12 seconds, an RPCError message is thrown.

If the routes are not returning, you can increase the time allocated to preparing the result by decreasing the soft timeout fraction and hence the time allocated to calculating the route.

If the timeout fraction is not specified, the GeoStream server returns an error at the end of the time limit. If the time limit is not specified, the timeout fraction setting is ignored.

Canceling slow vehicle history (route highlighting) requests

You can specify a time limit for route highlight requests, and the proportion of the time limit that should be used for calculating a route highlight before interrupting the calculation and returning the best available route highlight in the remaining time. To do this, insert the following keys:

<appSettings>
...
<add key="RouteHighlightTimeLimit" value="25"/>
<add key="RouteHighlightSoftTimeoutFraction" value="0.9"/>
...
</appSettings>

In the example above, the GeoStream server will attempt to return the route highlight result processed so far after 0.9 of 25 seconds (that is 22.5 seconds) and, if the result preparation does not finish in the remaining 2.5 seconds, an RPCError message is thrown.

If the route highlights are not returning, you can increase the time allocated to preparing the result by decreasing the soft timeout fraction and hence the time allocated to calculating the route highlight.

If the timeout fraction is not specified, the GeoStream server returns an error at the end of the time limit. If the time limit is not specified, the timeout fraction setting is ignored.

Canceling slow geocoding operations

To specify a time limit on geocode operations, for the AutocompleteGeocoder, GeoCoder and LocationSearch classes, insert the following key:

<appSettings>
...
<add key="GeocodingTimeLimit" value="60"/>
...
</appSettings>

In the example above, the GeoStream server cancels the geocode operation request if a result is not returned within 60 seconds. If the request is canceled, an RPCError message is thrown.

Canceling slow DataQuery operations

To specify a time limit on DataQuery operations insert the following key:

<appSettings>
...
<add key="DataQueryTimeLimit" value="30"/>
...
</appSettings>

In the example above, the GeoStream server cancels the DataQuery operation request if a result is not returned within 30 seconds. If the request is canceled, a DataQueryRequestException exception is thrown.

Canceling multicall operations

To specify a global time limit on multicall operations (that is, for all 'bulk' operations that include several calls, such as BulkGeoCode or bulk DataQuery requests such as BulkQueryLinks), insert the following key:

<appSettings>
...
<add key="MultiCallTimeLimit" value="120"/>
...
</appSettings>

In the example above, the GeoStream server cancels the request if a result is not returned within 120 seconds, or if the client disconnects. If the request is canceled, an RPCError message is thrown.

Inverting HERE traffic data

It is possible for the direction of traffic shown on a map to be inverted (that is, mirrored). This is typically caused by changes to the live traffic data supplied by HERE. To correct this problem, the FlipHERETraffic and InvertHERETraffic keys are provided.

To invert and flip the traffic displayed on maps, insert the following keys:

<appSettings>
...
<add key="FlipHERETraffic" value="true"/>
<add key="InvertHERETraffic" value="true"/>
...
</appSettings>

Rendering point address locations and labels on map tiles

If you are using point address data files, you can specify whether or not to render point address locations and labels on GeoStream map tiles using the option RenderPointAddresses. The option affects only newly generated tiles, not cached tiles. To ensure consistent map tiles, delete your GeoStream cache after changing the value. Default is "false".

To render point address locations and labels on map tiles, insert the following key:

<appSettings>
...
<add key="RenderPointAddresses" value="true"/>
...
</appSettings>

The default web.config file for new installations includes the RenderPointAddresses option with a value of true. If you do not want point address locations and labels to be rendered on map tiles, change the value of the key as follows:

<appSettings>
...
<add key="RenderPointAddresses" value="false"/>
...
</appSettings>

Other file locations

If you are using some of the optional config files such as TrafficConfig or UserInfoFile, you must add attributes to the web.config file to indicate where these files are located. You can add the following settings:

• UserInfoFile (for example key="UserInfoFile" value="userinfo.config")
• TrafficConfig (for example key="TrafficConfig" value="traffic.config")
• RedirectConfig (for example key="RedirectConfig" value="redirect.config")

You can specify the location of the language pack to use by setting the LangsFolder key. (for example key="LangsFolder" value="c:\MyData\langs")

In addition, if you are using CAM (Style) Files, you can use the DefaultStyle key to indicate the location of the CAM file that is used by default. For more information, see GeoStream CAM (Style) Files.

To define the name of the FriendsFile ensure that the web.config file contains the following syntax (in this example the FriendsFile is named friends.config):

<add key="FriendsFile" value="friends.config" />

This file details the clients of the server who do not need authentication. If a client’s IP address is within the IP range in the FriendsFile, the server allows access without any further checks. Entries in this file are of the form:

IP Range, User Name

Example

127.0.0.1/32, guest

192.168.3.0/24, guest

Note
The IP address range 0.0.0.0/0 permits the server to be open to all clients.

To define the name of the AuthFile ensure that the web.config file contains the following syntax (in this example, the AuthFile is named users.config):

<add key="AuthFile" value="users.config" />

This file details the clients that need to be authenticated. The format of this file is:

Example

guest, guest, 511

To define the name of the UserInfoFile ensure that the web.config file contains the following syntax (in this example the UserInfoFile is named userinfo.config):

<add key="UserInfoFile" value="userinfo.config" />

This file identifies vendor/country-specific datasets that the users are allowed to access. For each <user>, specify the datasets within the <AllowedDataSets> elements, as shown in the example below.

Example

<users>
<user id="511">
<AllowedDataSets>
<DataSet Ref="HERE_NA" />
<DataSet Default="true" Ref="HERECanada" />
<DataSet Ref="Tele_Atlas" />
</AllowedDataSets>
</user>
</users>

Notice that each dataset has a Ref attribute, which is used to point to the <DataFolder> in the RepositoryConfig file (see below).

A default dataset must be set, for when the user does not specify a dataset, using the Default attribute and setting its value to true.

To define the name of the RepositoryConfig file ensure that the web.config file contains the following syntax (in this example the RepositoryConfig file is named repository.config):

<add key="RepositoryConfig" value="repository.config" />

This file details the groups of datasets, as well as the locations on the server for the individual vendor/country-specific datasets. Datasets are grouped within a <DataFolder>. Each <DataFolder> can have one or more <DataSet> definitions attributed to it. Dataset file names do not have to be named explicitly; a wildcard (*) character can be used.

Names can be reused, as long as the nodes that share the name do not have the same parent. For example, you cannot define two folders within the <DataSets> node that share names, or multiple data sets within the same node (<DataSets> or <DataFolder>) that share names.

Only the data folders and data sets defined at the base level, as nodes that are directly underneath the <DataSets> node, are exposed on the GeoStream server. Users cannot directly address data sets that are nested within <DataFolder> nodes.

You can use <DataSetReference> to reference a <DataSet> or <DataFolder> that is defined at the base level of the RepositoryConfig file. This is useful if you want to define a number of dataset groups, each containing a combination of different datasets. Any duplicate datasets that result from combining the <DataSet> definitions are ignored. Datasets and folders can be referenced before they are defined.

You can specify a shared base path on the <DataSets> node. If you specify a relative path on the <DataFolder> node, the two portions of the path are joined. If you specify an absolute path on the <DataFolder> node, the shared path is ignored.

Example

<DataSets Path="m:\geobase\data\here">
<DataSet Name="Switzerland" FileName="here_Switzerland_*.gbfs" />
<DataSet Name="Belgium" FileName="here_Belgium_*.gbfs" />

<DataFolder Name="Europe" Path="m:\geobase\data\here">
<DataSet Name="Bulgaria" FileName="here_Bulgaria_*.gbfs" />
<DataSet Name="Romania" FileName="here_Romania_*.gbfs" />
<DataSetReference Name="EuropeWestern" />
<DataSetReference Name="Belgium" />
</DataFolder>

<DataFolder Name="EuropeWestern">
<DataSet Name="Denmark" FileName="here_Denmark_*.gbfs" />
<DataSetReference Name="Switzerland" />
<DataSetReference Name="Belgium" />
</DataFolder>

<DataFolder Name="HERE_NA" Path="m:\geobase\data\here">
<DataSet Name="HEREUSA" FileName="here_usa*.gbfs" />
<DataSet Name="HERECanada" FileName="here_canada_*.gbfs" />
</DataFolder>

<DataFolder Name="Tele_Atlas" Path="m:\geobase\data\teleatlas">
<DataSet FileName="*.gbfs" />
</DataFolder>
</DataSets>

To define the name of the RedirectConfig file ensure that the web.config file contains the following syntax (in this example the RedirectConfig file is named redirect.config):

<add key="RedirectConfig" value="redirect.config" />

This file is used to specify the JSON-RPC requests that will be directed to some or all members of a pool of dynamically balanced worker GeoStream servers.

For example, to specify GetDirections and GetQuickDirections method tasks be distributed across three servers in a cluster, but GeoCode method tasks be restricted to only one of these three, use RedirectConfig file like the one in the following example:

<Redirect>
<Method name="GetQuickDirections" serverGroupId="routing"/>
<Method name="GetDirections" serverGroupId="routing"/>
<Method name="GeoCode" serverGroupId="geocoding"/>
<Servers>
<Server url="http://geostream.workerserver.1">
<MemberOf groupId="routing"/>
<MemberOf groupId="geocoding"/>
</Server>
<Server url="http://geostream.workerserver.2">
<MemberOf groupId="routing"/>
</Server>
<Server url="http://geostream.workerserver.3">
<MemberOf groupId="routing"/>
</Server>
</Servers>
</Redirect>

This configuration file should be present only on the parent server in the cluster, not on the worker servers.

The serverGroupId parameter is an arbitrary server group name, while the Method parameter is populated with titles that represent JSON-RPC (Remote Procedure Call) remote method invocations that are provided for various GeoBase methods. Typically, this technique will be used to balance resource-intensive methods such as:

• GeoCode

• Route

• GetDirections

• GetQuickDirections

• RouteMatrix

To define the name of the TrafficConfig file add the following syntax into the web.config file (in this example the TrafficConfig file is named traffic.config):

<add key="TrafficConfig" value="traffic.config" />

This file details the traffic sources for the traffic layers. It also supports authentication, multiple URLs, file compression, traffic server fetch timeout, and the source refresh rate.

An example TrafficConfig file is shown below.

<?xml version="1.0" encoding="utf-8" ?>
<Traffics>
<Traffic ID="TrafficData" xmlns:gb="Telogis.GeoBase.Traffic" Refresh="1:00" FetchTimeout="00:00:15" prestyle="preTraffic.cam">
<gb:InrixRealTimeTrafficSource>
<Source Url="http://traffic.geobase.info/SourceA.xml" />
<Source Url="http://traffic.geobase.info/SourceB.xml.zip" Zipped="true" />
<Source Url="http://traffic.geobase.info/SourceC.xml.zip" /> <!-- Zipped=true based on extension -->
<Source Url="http://traffic.geobase.info/SourceD.xml.gz" GZipped="true" />
<Source Url="http://traffic.geobase.info/SourceE.xml.gz" /> <!-- Zipped=true based on extension -->
<Source Url="http://traffic.geobase.info/SourceF.xml" Username="user" Password="password1"/> <!-- authentication -->
</gb:InrixRealTimeTrafficSource>

<gb:NavteqRealTimeTrafficSource GZipped="true" Username="user" Password="password2">
<Source Url="http://traffic.geobase.info/SourceH.xml.gz"/>
<Source Url="http://traffic.geobase.info/SourceI.xml.gz"/>
<Source Url="http://traffic.geobase.info/SourceJ.xml.gz" Password="password3"/>
</gb:NavteqRealTimeTrafficSource>

<gb:NavteqRealTimeTrafficSource Url="http://traffic.geobase.info/SourceK.xml.gz" />
</Traffic>
</Traffics>

Multiple URLs

Each Traffic node can optionally specify one or more sources, as shown above. Sources inherit all attributes from the parent element but can override them. If a source is specified, a URL must not be specified on the parent element.

Authentication

HTTP Authentication is enabled by specifying a username and password.

File compression

Zip or GZip compression is automatically used based on the URL's extension (.zip or .gz respectively). Alternatively, compression can be specified manually using the attributes Zipped="true" and GZipped="true".

Refresh rate

Set the refresh rate on the <Traffic> element. The refresh rate has a minimum value of 10 seconds. If you do not supply a refresh rate, the default value is 5 minutes.

For backward compatibility, a refresh rate can also be set on a Source node (as long as the traffic source supports a refresh property). All built-in traffic sources support a refresh property, but this might not be the case with custom traffic sources. When you set a refresh rate on one or more traffic sources, the shortest refresh period (whether set on the <Traffic> element or on any of its child nodes) is used for all traffic sources.

Traffic server fetch timeout

Use the FetchTimeout attribute, to automatically re-trigger the traffic request for when a previous request times out. In the example above, the attribute has been set to 15 seconds; the default is 30 seconds.

PreStyle

Specifies an optional additional style file. This style is rendered, with the PRE_TRAFFIC parameter set, onto the traffic overlay tiles before the traffic flow lines are rendered. This is intended to allow greyscale versions of road networks to be rendered with the traffic tiles, occluding the brightly colored road network rendered in the basemap tiles, increasingly the contrast of the traffic flow lines for easier comprehension. Paths can be absolute, or relative to the GeoStream server's bin folder.

Proactive traffic fetching

Use the Boolean attribute FetchProactively on the Traffic element to define whether traffic should be fetched proactively or not. When set to true, new traffic data is fetched from the traffic sources before the previous traffic data expires. Proactive traffic fetching is disabled (false) by default.

This is an example of a Traffic element with FetchProactively enabled:

<Traffic ID="TrafficData" xmlns:gb="Telogis.GeoBase.Traffic" Refresh="0:05" FetchProactively="true">

Historical traffic data

Traffic sources can be configured to provide historical traffic data, using local gbhb files as data sources.

To do this, you must define one or more gb:HistoricalTrafficSource XML elements with the following parameter:

DataFiles - A list of gbhb files to use as data sources, separated by the path separator (a semi-colon (;) on Windows). The file path can contain asterisks (*) as wildcard characters. For example: DataFiles="C:\Resources\data\HERE_CanadaTraffic_*.gbhb;C:\Resources\data\HERE_USATraffic_*.gbhb".

For example, to include historical traffic data for Canada, add the following entry into the TrafficConfig file:

<Traffic ID="HistoricalTraffic" xmlns:gb="Telogis.GeoBase.Traffic" DefaultFor="historic">
  <gb:HistoricalTrafficSource DataFiles="C:\Resources\data\HERE_CanadaTraffic_*.gbhb"/>
</Traffic>

To define the name of the LayersConfig file ensure that web.config contains the following syntax (in this example the LayersConfig file is named layers.config):

<add key="LayersConfig" value="layers.config" />

This file specifies the types of data that can be displayed on a GeoStream map, for example you can configure radar, cloud, temperature, wind, and satellite layers. You can configure XYZ layers for satellite imagery, WMS layers for other information, as well as Baron layers , which are specialized WMS layers.

XYZ layer

The code below shows the syntax for configuring XYZ layers in the LayersConfig file to display satellite imagery.

XML

Copy

<XYZLayer
Name="XYZSatellite"
RenderMode="underlay"
Url="http://imagery1.telogis.com/ImageryCache/xyz/Satellite/{z}/{x}/{y}"
RetinaUrl="http://imagery1.telogis.com/ImageryCache/xyz/Satellite/{z}/{x}/{y}/512"
AuthUrl="http://imagery1.telogis.com/ImageryCache/"
ExpiryMinutes="-1"
Copyright=""
Description="Satellite tiles requested using XYZ request format from Verizon Connect GeoStream ImageryCache."
RequestTimeoutSeconds="20"
Cacheability="private"
ClientExpiryMinutes="60" />

Note that the Url attribute value is HTML-encoded. That is, the parameters in the Url must be separated by &amp;.

For XYZ layers to work correctly with GeoBase, the layer server must provide layers in Spherical Mercator projection, where the a and b parameters are set to 6378137. Suitable codes for this projection are:

• EPSG:3857

• EPSG:3785

• Google Projection (often called EPSG:900913)

• ESRI:102113

• ESRI:102100

The underlying data must be in WGS84 datum.

XYZ layer configuration attributes

The following table describes the attributes for configuring XYZ layers.

Attribute	Purpose
Name	Layer name
Url	The layer request. This is a standard XYZ request, except it has no bounding box, width or height parameters - these are added automatically by GeoBase for you. The co-ordinate system for the bounding box is set with the parameter "&SRS=EPSG:102113" or "&SRS=EPSG:4326" (WGS84).
RetinaUrl	The layer request for a retina tile. This is a standard XYZ retina request, except it has placeholders for zoom {z} and x and y coordinates ({x} and {y}). The placeholders are automatically replaced by GeoBase for you.
LegendUrl	The URL for the image's legend. Optional attribute. An empty response is returned if the user requests a legend for a layer which does not have this parameter.
ExpiryMinutes	Time in minutes before layer is refreshed. Optional attribute. Default is 60. If ExpiryMinutes is set to 0, the layer never times out. If ExpiryMinutes is set to a negative number, the layer times out immediately.
ClientExpiryMinutes	Time in minutes that a tile remains in the browser cache. When not set, GeoStream uses the value specified by ExpiryMinutes. When set to 0, tiles stay in the browser cache indefinitely. When set to a negative number, the tiles are immediately expired from the browser cache.
TilePortionAllowedErrorStrings	Comma separated list of error strings. When retrieving an error response from the XYZ provider, errors that are specified in this setting are ignored. Instead, the errors are treated as a valid, but empty, response. A use case for using this setting is for a layer that is only valid for part of the world, so you want GeoBase to return empty 200 responses for requests outside of the area. Optional attribute. Default is an empty string.
Copyright	Copyright information. Optional attribute. Default is "".
Description	Description of layer. Optional attribute. Default is "".
Tag	A tag for the layer, such as "Weather". Optional attribute. Default is "".
RequestTimeoutSeconds	The number of seconds to wait before timing out requests to the provider. Optional attribute. Default is 30 seconds.
UnresponsiveRequestTimeoutSeconds	When in an unresponsive state, this value specifies the number of seconds to wait before timing out requests to the provider. Optional attribute. Default is one third of RequestTimeoutSeconds, with a lower cap of the lower of 5 seconds and RequestTimeoutSeconds.
UnresponsiveErrorThreshold	The number of consecutive failing requests to the provider that can occur before the unresponsive request timeout is used. Optional attribute. Default is 3. Set to 0 to disable shorter timeouts for consecutive errors.
UnresponsiveErrorProportionThreshold	The proportion of failing requests to the provider that can be reached before the unresponsive request timeout is used. The proportion is calculated based on the value specified for UnresponsiveErrorSampleSize. Optional attribute. Default is 0.3. Set to 0 to disable shorter timeouts for high failure proportions.
UnresponsiveErrorSampleSize	The sample size to use when calculating whether UnresponsiveErrorProportionThreshold has been exceeded. Optional attribute. Default is 20. Set to 0 to disable shorter timeouts for high failure proportions.
UserAgent	A User-Agent HTTP header containing details about the requesting application. Add this header when using National Oceanic and Atmospheric Administration (NOAA) weather layers because it resolves some reliability issues. The recommended format when used with these layers is <product name>/<version> (<contact email>). Optional attribute. No User-Agent header is included if this attribute is not specified.
AuthUrl	The URL used to acquire an authentication token for the layer. This setting is used primarily for satellite layers that connect to an ImageryCache.
AuthType	The authentication type required for this layer. If not specified, the authentication type is "Default", which means that no special authentication is required.
RenderMode	A render mode for the layer. Optional attribute. Set to "underlay" to show as a basemap layer or "overlay" to show as a layer on top of the basemap layer. Default is "overlay".
Username	The username for authenticating to the provider using basic HTTP access authentication. Optional attribute.
Password	The password for authenticating to the provider using basic HTTP access authentication. Optional attribute.
Cacheability	The value to use for the cacheability header in the image response. Supported values are public, private, and nocache. Optional attribute. Default is public.

Note
When using authentication credentials use HTTPS, if possible, because the credentials are sent in plain text as part of the request header.

WMS layer

The code below shows the syntax for configuring WMS layers in the LayersConfig file to display temperature and cloud data.

WMS layers should no longer be used for displaying satellite imagery. Instead, you can use XYZ layers for displaying satellite imagery. WMS layers can be used for defining Baron layers, fallback imagery, or opacity, and for composing multiple overlay into a single overlay image.

XML

Copy

<WMSLayer
Name="Temperature"
Username="johnsmith"
Password="ABCD1234!@#$"
Url="http://nowcoast.noaa.gov/wms/com.esri.wms.Esrimap/analyses?service=wms&amp;version=1.1.1&amp;request=GetMap&amp;SRS=EPSG:102113&amp;format=png&amp;transparent=true&amp;Layers=RTMA_RAS_AIRTEMP"
Opacity="30"
ExpiryMinutes="10"
MaxTileSize="1200"
UserAgent="GeoStream (contact: customer@email.com)"/>
<WMSLayer
Name="Cloud"
Url="https://nowcoast.noaa.gov/arcgis/services/nowcoast/sat_meteo_imagery_time/MapServer/WMSServer?request=GetMap&service=WMS&version=1.3.0&SRS=EPSG:3857&CRS=EPSG:3857&styles=default&format=png&transparent=true&Layers=9"
LegendUrl=""
Opacity="75"
ExpiryMinutes="10"
MaxTileSize="1200"
TilePortionAllowedErrorStrings="MS_E_NOIMAGERETURNED"
Copyright=""
UserAgent="GeoStream (contact: customer@email.com)"
Description="Visible Satellite Cloud Imagery"
Tag="Weather"/>

Note that the Url attribute value is HTML-encoded. That is, the parameters in the Url must be separated by &amp;.

For WMS layers to work correctly with GeoBase, the layer server must provide layers in Spherical Mercator projection, where the a and b parameters are set to 6378137. Suitable codes for this projection are:

• EPSG:3857

• EPSG:3785

• Google Projection (often called EPSG:900913)

• ESRI:102113

• ESRI:102100

The underlying data must be in WGS84 datum.

WMS layer configuration attributes

The following table describes the attributes for configuring WMS layers. For details on additional configuration for Baron layers, see the Baron Layer attribute descriptions .

Attribute	Purpose
Name	Layer name
Url	The layer request. This is a standard WMS request, except it has no bounding box, width or height parameters - these are added automatically by GeoBase for you. The co-ordinate system for the bounding box is set with the parameter "&SRS=EPSG:102113" or "&SRS=EPSG:4326" (WGS84). For Baron layer configuration, see the Url attribute description for Baron layers.
LegendUrl	The URL for the image's legend. Optional attribute. An empty response is returned if the user requests a legend for a layer which does not have this parameter.
Opacity	Layer opaqueness - set between 0 and 100. Optional attribute. Default is 50.
ExpiryMinutes	Time in minutes before layer is refreshed. Optional attribute. Default is 60. If ExpiryMinutes is set to 0, the layer never times out. If ExpiryMinutes is set to a negative number, the layer times out immediately. For Baron layer configuration, see the ExpiryMinutes attribute description for Baron layers.
ClientExpiryMinutes	Time in minutes that a tile remains in the browser cache. When not set, GeoStream uses the value specified by ExpiryMinutes. When set to 0, tiles stay in the browser cache indefinitely. When set to a negative number, the tiles are immediately expired from the browser cache.
Cacheability	The value to use for the cacheability header in the image response. Supported values are public, private, and nocache. Optional attribute. Default is public.
MaxTileSize	The maximum tile size, in pixels, to be received from the WMS server. Optional attribute. Default is unlimited.
TilePortionAllowedErrorStrings	Comma separated list of error strings. When retrieving an error response from the WMS provider, errors that are specified in this setting are ignored. Instead, the errors are treated as a valid, but empty, response. A use case for using this setting is for a layer that is only valid for part of the world, so you want GeoBase to return empty 200 responses for requests outside of the area. Optional attribute. Default is an empty string.
Copyright	Copyright information. Optional attribute. Default is "".
Description	Description of layer. Optional attribute. Default is "".
Tag	A tag for the layer, such as "Weather". Optional attribute. Default is "".
RequestTimeoutSeconds	The number of seconds to wait before timing out requests to the provider. Optional attribute. Default is 30 seconds.
UnresponsiveRequestTimeoutSeconds	When in an unresponsive state, this value specifies the number of seconds to wait before timing out requests to the provider. Optional attribute. Default is one third of RequestTimeoutSeconds, with a lower cap of the lower of 5 seconds and RequestTimeoutSeconds.
UnresponsiveErrorThreshold	The number of consecutive failing requests to the provider that can occur before the unresponsive request timeout is used. Optional attribute. Default is 3. Set to 0 to disable shorter timeouts for consecutive errors.
UnresponsiveErrorProportionThreshold	The proportion of failing requests to the provider that can be reached before the unresponsive request timeout is used. The proportion is calculated based on the value specified for UnresponsiveErrorSampleSize. Optional attribute. Default is 0.3. Set to 0 to disable shorter timeouts for high failure proportions.
UnresponsiveErrorSampleSize	The sample size to use when calculating whether UnresponsiveErrorProportionThreshold has been exceeded. Optional attribute. Default is 20. Set to 0 to disable shorter timeouts for high failure proportions.
UserAgent	A User-Agent HTTP header containing details about the requesting application. Add this header when using National Oceanic and Atmospheric Administration (NOAA) weather layers because it resolves some reliability issues. The recommended format when used with these layers is <product name>/<version> (<contact email>). Optional attribute. No User-Agent header is included if this attribute is not specified.
AuthUrl	The URL used to acquire an authentication token for the layer. This setting is used primarily for satellite layers that connect to an ImageryCache.
AuthType	The authentication type required for this layer. If not specified, the authentication type is "Default", which means that no special authentication is required. For Baron layer configuration, see the AuthType attribute description for Baron layers.
RenderMode	A render mode for the layer. Optional attribute. Set to "underlay" to show as a basemap layer or "overlay" to show as a layer on top of the basemap layer. Default is "overlay".
EnableRetina	Indicates whether retina requests are enabled for this layer. If true, tiles are requested at twice the resolution. If false, normal tiles are requested and then scaled up. Default is "true".
AllowFallback	Whether to allow for fallback imagery to be returned instead of a 500 error when external providers fail to return the requested imagery. Set to true to allow fallback imagery. This is currently supported for layers using Verizon Connect GeoStream ImageryCache. Fallback images are not cached and not guaranteed when this option is used. Optional attribute. Default is "false".
SubstituteLayerNameForLowZooms	The substitute layer name for the layer to use when zoomed out. Also specify MaximumSubstituteZoom if you want to use a substitute layer at low zoom levels. Optional attribute. Default is "".
MaximumSubstituteZoom	The highest zoom value up to which the substitute layer with the name SubstituteLayerNameForLowZooms should be used. The zoom value corresponds to the world width in supertiles and is normally a power of 2. Also specify SubstituteLayerNameForLowZooms if you want to use a substitute layer at low zoom levels. Optional attribute. Default is 0.
Username	The username for authenticating to the provider using basic HTTP access authentication. Optional attribute.
Password	The password for authenticating to the provider using basic HTTP access authentication. Optional attribute.

Note
When using authentication credentials use HTTPS, if possible, because the credentials are sent in plain text as part of the request header.

Baron layers

A Baron layer is a specialized type of WMS layer that requires additional configuration.

Note
Baron is a third-party data provider that specializes in delivering critical weather information. For more information on using Baron data in your applications, contact your account manager or GeoBase support.

Baron layer configuration attributes

The following table describes the additional configuration attributes and instructions for configuring a Baron layer in the LayersConfig file.

Attribute	Purpose
AuthType	The authentication type required for this layer. For a Baron weather layer, set this to "Baron". If not specified, the authentication type is "Default", which means that no special authentication is required. Required attribute for Baron layers.
Url	The layer request. The Url format for the Baron layer request depends on whether the layer provides forecasting data. For a non-forecasting Baron weather layer, the URL must point to the Baron API and include the tokens "{AccessKey}", "{ProductCode}", and "{TimeStep}". For example, http://api.velocityweather.com/v1/{AccessKey}/wms/{ProductCode}/Standard-Mercator?VERSION=1.3.0&SERVICE=WMS&REQUEST=GetMap&CRS=EPSG:3857&LAYERS={TimeStep} The "{AccessKey}" and "{ProductCode}" tokens are automatically replaced by the values specified in the configuration settings when the GeoStream server parses the LayersConfig file. Each time a request is made, the GeoStream server automatically replaces "{TimeStep}" with the most recent data that Baron has provided for that layer. For a forecast Baron layer, append the token "{ForecastTime}" to the URL after the "{AccessKey}", "{ProductCode}", and "{TimeStep}" tokens as shown in the following example: http://api.velocityweather.com/v1/{AccessKey}/wms/{ProductCode}/Standard-Mercator?VERSION=1.3.0&SERVICE=WMS&REQUEST=GetMap&CRS=EPSG:3857&LAYERS={TimeStep}&TIME={ForecastTime}
AccessKey	The Baron access key to access Baron weather data. Required for a Baron layer.
SecretKey	The Baron secret key to access Baron weather data. Required for a Baron layer.
ProductCode	The Baron product code for the Baron weather layer. Required for a Baron layer.
TimeStepUrl	The JSON time step URL for fetching the product weather data when using a Baron weather layer. Set this value to http://api.velocityweather.com/v1/{AccessKey}/meta/tiles/product-instances/{ProductCode}/Standard-Mercator.json. The tokens "{AccessKey}" and "{ProductCode}" are automatically replaced by the GeoStream server. Required for a Baron layer.
TimeStepUpdateMinutes	This value represents the rate at which Baron publishes new data for a forecast layer. For example, the Baron service updates the surface temperature layer data every 10 minutes. This value is used in conjunction with ExpiryMinutes to calculate the expiration for a cached Baron weather layer. Required attribute for Baron forecast layers. Use the value indicated in the Baron data catalog.
ExpiryMinutes	For Baron forecast layers, this value is used to calculate when tiles from a Baron forecast layer expire and need to be fetched again from the external provider. Set the "ExpiryMinutes" value to the time span (in minutes) between any two consecutive timestamps in the time step forecast data published by Baron. The following example shows the Baron forecast data published for a time step update that occurs every 10 minutes. Each time step provides forecast data timestamps at 5 minute intervals. ini Copy TimeStep1 Time 1 forecast for 1:00 PM Time 2 forecast for 1:05 PM Time 3 forecast for 1:10 PM Time 4 forecast for 1:15 PM Time 5 forecast for 1:20 PM Time 6 forecast for 1:25 PM Time 7 forecast for 1:30 PM Time 8 forecast for 1:35 PM For this forecast data, the "ExpiryMinutes" value is 5 minutes (Time 2 - Time 1). Required for Baron forecast layers.
MinutesInFuture	For Baron forecast layers, this value indicates how many minutes in the future, compared to the current time, that the forecast is for. For example, if this value is set to 120, the forecast is for 2 hours from the current time. Required for Baron forecast layers.
LegendDataUrl	The URL for programmatically generated legends. Set this attribute to http://static.velocityweather.com/legends/{ProductCode}/Standard-Mercator/legend.{Extension}. The GeoStream automatically replaces {ProductCode} and {Extension} with the appropriate values. This configures the Baron API endpoint that is used to get the data from which the legend is generated. The legend is accessible through the /image.aspx?type=legend&layer=<layer_name> endpoint of the GeoStream. Optional attribute. LegendUrl is used in preference to LegendDataUrl, if it is specified and points to a valid legend image. LegendDataUrl is used only if LegendUrl is omitted. If neither LegendUrl nor LegendDataUrl are set, no legend will be available for the layer.

If you are upgrading your GeoStream server from a version that does not use XYZ satellite imagery, you must edit two configuration files (web.config and the LayersConfig file) to enable this capability. When you installed GeoBase these two files were placed in Program Files\Telogis\GeoBase\GeoStream\server.

Navigate to this folder and open the web.config file. Remove the following line (typically line 15):

<add key="SatelliteHost" value="http://imagery1.telogis.com/ImageryCache/" />

Replace with the following:

<add key="XYZSatelliteLayer" value="XYZSatellite" />

Save web.config and open the LayersConfig file. Add the following to the Layers list:

<XYZLayer
    Name="XYZSatellite"
    RenderMode="underlay"
    Url="http://imagery1.telogis.com/ImageryCache/xyz/Satellite/{z}/{x}/{y}"
    RetinaUrl="http://imagery1.telogis.com/ImageryCache/xyz/Satellite/{z}/{x}/{y}/512"
    AuthUrl="http://imagery1.telogis.com/ImageryCache/"
    ExpiryMinutes="-1"
    Copyright=""
    Description="Satellite tiles requested using XYZ request format from Verizon Connect GeoStream ImageryCache."
    RequestTimeoutSeconds="20"
    Cacheability="private"
    ClientExpiryMinutes="60" />

Save the LayersConfig file. When you restart the GeoStream server, the server can serve XYZ satellite imagery.

Enabling Satellite Imagery

Note
Only clients who have a valid Satellite Imagery contract have a Username and Password for this service. If you have a valid contract, but do not know your username and password, contact GeoBase Support at gbsupport@verizonconnect.com.

To enable your Satellite Imagery account on your GeoStream server, edit the web.config file, adding the following two key values in the <appSettings> block (below the 'XYZSatelliteLayer' key). Replace the username and password details with the unique credentials provided to you by Verizon Connect.

<add key="SatelliteUser" value="USERNAME" />
<add key="SatellitePass" value="PASSWORD" />

If present, the following key entry must be removed:

<add key="SatelliteAuthKey" value="VALUE" />

Save web.config and restart IIS. Satellite imagery should now be available.

The GeoStreamConfig file contains additional GeoStream configuration options. You can use it to set the limits for worker pools. Worker pools are used to manage incoming requests and allocate resources optimally based on the ability of the server.

To define the name of the GeoStreamConfig file ensure that web.config contains the following syntax (in this example the GeoStreamConfig file is named geostream.config):

<add key="GeoStreamConfig" value="geostream.config" />

By default, the work intensive and wait intensive worker pools have a queue size (QueueSize) of 10 and a background queue size (BackgroundQueueSize) of 40. The wait intensive pool has 16 active slots (ActiveTasks), while the work intensive pool has as many slots (ActiveTasks) as processors on the server, with a minimum of 4.

You can optionally specify a queue time (QueueTime), which represents the limit of the expected waiting time, in seconds, before a task is processed. If a queue time is set, a task is rejected if either the queue time or the queue size is exceeded.

These values can be customized within the GeoStreamConfig file as shown in the code below. To customize the values for one pool only, just omit the other pool. If you omit any of the limits, their default values are used.

An example of a GeoStreamConfig file:

<?xml version="1.0" encoding="utf-8"?>
<config>
<WorkerPools>
<WorkerPool Type="WorkIntensive" ActiveTasks="4" BackgroundQueueSize="40" QueueSize="100" QueueTime="10"/>
<WorkerPool Type="WaitIntensive" ActiveTasks="16" BackgroundQueueSize="40" QueueSize="100" QueueTime="10"/>
</WorkerPools>
</config>

Before a JavaScript client can access a GeoStream server directly, and when the web application server and the GeoStream server are not on a trusted network, authentication is handled between the web application server and the GeoStream server. In this situation, only the GeoStream server has a copy of the server key.

If the web application server and the GeoStream server form part of a trusted network, the server key can be shared. With a shared server key, the authentication process can be handled by the web application server alone, thus negating the need to communicate with the GeoStream server, and consequently speeding up the service.

With high-traffic installations, it is common for multiple GeoStream servers to be connected to the internet via a load balancer (see the image below). The load balancer makes the decision about which GeoStream server to access, and so it is important in this situation, that each server has the same copy of the server key. Having the same server key distributed across the servers, ensures that subsequent client requests can be acted upon, with the same authentication token, by any of the servers connected to the load balancer.

The Authentication Process with .NET Client