Guzzler API

Amy Holland — Wed, 21 Apr 2010 21:26:43 GMT

Guzzler API

General Usage Pattern:

Call GuzzlerOpen() to obtain a handle.

You can then create drive time polygons by calling GuzzlerBuildPolygons() followed by either GuzzlerGetPolygons() (to get a memory buffer) or GuzzlerWritePolygons() (to go directly to a file).

Alternatively, you can run Point-To-Point drive times by calling GuzzlerXMLRequest()

Call GuzzlerClose() to close the engine.

Engine Open/Close

GuzzlerListDataSets

Description:
Retrieve XML listing the available datasets on the system.

Return const wchar_t *:
A pointer to a buffer containing an XML listing of the available data sets, the XML will have the form:

The values in the "Name" attributes are what can be passes to GuzzlerOpen. The "Description" attribute is the human-readable name.

GuzzlerOpen

Description:
Open the engine

Return void *:
the handle to use for subsequent API calls; NULL in case of error

Arguments:
const char *pDataSet : The name of the dataset to use; specifically, this value tells the engine where to find the XML Settings node to use for this run. In the simpler cases, NULL will use the default data set, a country code will use the default for that country, and the name of a data set will use that set (with default settings).

char *pErrorReturn : A pointer to a buffer of at least 256 chars

GuzzlerClose

Description:
Close the engine

Arguments:
void * handle: the handle returned from GuzzlerOpen

GuzzlerGetLastError

Description:
Retrieve an error message

Return char *:
The error message

Arguments:
void * handle: the handle returned from GuzzlerOpen

Polygon Generation

GuzzlerBuildPolygons

Description:
Create DriveTimes around a point

Return long:
the number of polygons created

    Arguments:
        void * handle: the handle returned from GuzzlerOpen
        double dLat: the latitude of the start point
         double dLong: the longitude of the start point
        const char * pDriveTimes: a comma separated list of times, in minutes.

Note: if running multiple times around a single point, it will be more efficient to use a single call to GuzzlerBuildPolygons()

GuzzlerGetPolygon

Description:
Returns a polygon from the engine. GuzzlerBuildPolygons must be called 1st

Return long:
0 if failure. non-0 for success

    Arguments:
        int handle: the handle returned from GuzzlerOpen
        long nWhich: a number >=0 and < the return from BuildPolygons
        long *pNumPoints: The number of points returned
        double **pThePointsX: A pointer to buffer that will have the X Points. This buffer will get overwritten by the next call to GuzzlerGetPolygon and should be copied if needed.
        double **pThePointsY: A pointer to buffer that will have the Y Points. This buffer will get overwritten by the next call to GuzzlerGetPolygon and should be copied if needed.

GuzzlerWritePolygons

Description:
Writes the polygons to a file. GuzzlerBuildPolygons must be called 1st

Return long:
0 if failure. non-0 for success

    Arguments:
        void * handle: the handle returned from GuzzlerOpen
        const char *pSpatialFile: The filename to write polygons to. Format will be deduced from the extension

Point-to-Point

GuzzlerXmlRequest

Description:
Runs Point-to-Point drivetime requests.

Return const wchar_t *:
A pointer to wide-character string containing the results of the drive time calculations in XML as described below. This buffer will be overwritten by the next call to GuzzlerXmlRequest.

    Arguments:
        void * handle: the handle returned from GuzzlerOpen
        const wchar_t * xmlIn: a wide character string containing a point-to-point drive time request in XML as described below

Input XML format:

Example:

Nodes/Attributes:

GuzzlerRequest : the root node

Mode: Currently, only "PointToPoint" is supported.

Options : sets options that control how the request is processed

DistanceOnly : (optional, defaults to false) if this is set to false (or omitted), the engine will find the minimum time route between points, and report the time and distance for that route. If this is set to true, the engine will find the minimum distance route (which may be different) and report only the distance.
Max: the maximum drive time (or distance in distance-only mode) to consider. The engine will continue searching the road network until a route is found between the start and end points, or until the nodes it is considering are further from the start than this time/distance. Start and end nodes which are inordinately far apart (or even unconnected) will cause an excessively long search if this not set to a reasonable value.

From : The start point

X : The start Longitude, in decimal degrees
Y : The start Latitude, in decimal degrees

To: The end point(s); there should be one of these nodes for each destination point. When running multiple point-to-point drive times from a single start point, it will be considerable more efficient to run them together

X : The start Longitude, in decimal degrees
Y : The start Latitude, in decimal degrees
Id: (optional) This field will be passed through to the output XML, and may be helpful in identifying the result nodes, whose order is not guaranteed; its contents can be anything

Output XML format:

Example:

Description:

The Output XML consists of a GuzzlerResult Node containing all the same information from the GuzzlerRequest input node, except that each "To" node will have the additional attributes "Time" containing the drive time in minutes, and "Distance containing the distance in miles. If the request set "DistanceOnly" to true, the "Time" attribute will be omitted. Both attributes will be omitted if the engine cannot find a route that takes less than the max time setting.

Meta Info

Description:

The GuzzlerXMLRequest function used for point-to-point drivetimes can also be used to retrieve (very limited) meta information. Specifically, it will provide the StartNodeSearchDistance and the maximum road speed for the currently loaded data set. With these two numbers it is possible to determine the theoretical maximum distance from a start point that may be reached within a given start time. This can be used to pre-filter point-to-point requests to avoid passing in destinations that are obviously unreachable. Both of these values could theoretically be derived from the settings file, but by pulling them through the API we avoid duplicating the data set selection and parsing logic. Note; that even if the settings file uses kilometers, the numbers will be reported in miles.

Example Input:

To retrieve this Meta info, pass the following to GuzzlerXMLRequest:

Example Output:

The returned XML will resemble:

60
2.00

Guzzler – Usage Example

Guzzler Example Code

This example opens the guzzler engine, generates some polygons, writes them to a file, retrieves one of them directly in memory, and writes out a list of the points in it.

char pErrorBuff[256];

const char * pError;

long nReturn;

void * handle;

long numPolys;

long numPoints;

double * pThePointsLat;

double * pThePointsLong;

//0pen the engine, specifying the name of the data set to use. Pass NULL to just get the default

handle = GuzzlerOpen("TA_US_Q306", pErrorBuff);

if (handle==NULL)

{

printf("Error opening Guzzler: %s\n", pErrorBuff);

return 0;

}

// Build 5, 10 & 15 minute rings around a point

numPolys = GuzzlerBuildPolygons(handle, 40.036617, -105.256585, "5,10,15");

if (numPolys != 3)

{

pError = GuzzlerGetLastError(handle);

printf("Unexpected return from BuildPolygons: %s\n", pError);

return 0;

}

// write them to a shape file

nReturn = GuzzlerWritePolygons(handle, "c:/temp/test.shp");

if (nReturn==0)

{

pError = GuzzlerGetLastError(handle);

printf("Error writing polygons: %s\n", pError);

}

// retrieve the 5 minute poly into memory

nReturn = GuzzlerGetPolygon(handle,0,&numPoints,&pThePointsLat,&pThePointsLong);

if (nReturn==0)

{

pError = GuzzlerGetLastError(handle);

printf("Error in GetPolygon: %s\n", pError);

return 0;

}

//do something with it

printf("# Latitude Longitude\n");

for (unsigned x = 0; x < numPoints; x++)

{

printf("%4d %10.5f %10.5f\n",x,pThePointsLat[x],pThePointsLong[x]);

}

// close the engine

GuzzlerClose(handle);

Resolving a Guzzler Data Set Specification

When Guzzler is called via the API, GuzzlerOpen() it is given a string (the first argument) specifying what data set / settings to use. The handling of this argument is intended to provide considerable flexibility, and thus the full process is somewhat complex, but most actual usage cases should be fairly simple. The complete logic is described at the end of this document.

If your settings file has only one set of settings, you may:

Pass NULL, or an empty string to use the default dataset; This is specified by the "CurrentDbSet" registry entry.
Pass a country code to use the default for that country; e.g. pass "UK" to use the data set specified by "CurrentDbSet_UK"
Pass the name of a dataset to use that set explicitly.

Once the data set is identified, the corresponding "DataFilePath" and "SettingsFileName" are used to identify the xml settings file, and the default (or only) SrcGuzzlerSettings node from the file is used.

A settings file may contain multiple SrcGuzzlerSettings nodes specifying different speeds for different times of day, or even different data files for different countries, all grouped as one "DataSet". The settings nodes in such a file should each have a "Name" attribute, and can be selected by following the data set name with a dot "." and the name of the settings node to use. Such a settings file might look something like this (actual Road Types omitted for brevity, presumably they would differ in the different sets):

...

Assuming the Registry had a dataset named "MyDataSet" pointing at this XML settings file, you could then pass GuzzlerOpen() just "MyDataSet" to get the "Normal" settings, since they are identified as the default. But you could also pass "MyDataSet.RushHour" to get RushHour settings instead.

Note that Settings nodes can be nested to any depth. So, for example, if you wanted to manage multiple countries in one settings file, as well as times of day, you could have something like:

...

And then specify the settings to use as "MyDataSet.UK.RushHour"

Complete logic:

The string is broken on periods (".") and the first token (which may be the whole string) is used to identify which data set in the registry to use:

If the first token is empty (because pDataSet is NULL or points to an empty string, or the string starts with a period) the engine will use the default data set (i.e. the only or most recently installed), identified by the registry value "CurrentDbSet"

If the first token is not empty, the engine will look for a data set (key) in the registry that matches, and use that.

If there is no matching data set, the engine will try to use the first token as a country code, by looking for a registry value named "CurrentDbSet_" (replacing "" with the first token), and will use the data set specified. If this check fails, an error is returned.

Having identified a data set, the engine will use the DataPath and SettingsFileName registry values to load the settings XML file. If breaking pDataSet on periods resulted in more than one token (i.e. the string actually contained one or more periods), the engine will match these tokens to nodes in the XML by looking for a child of the root node that has a "Name" attribute whose value matches the second token, a child of this node whose "Name" matches the third token, etc. Failure to find a match at any level is an error.

Once all tokens are exhausted, the resulting XML node is considered: if it is a valid settings node (i.e. a "SrcGuzzlerSettings" element, with children named "DataFile", "RoadTypes", etc.) it will be used. If it instead contains children that are themselves SrcGuzzlerSettings nodes, the engine will take the first one with an attribute "Default" set to "True", or the first in document order. This node will then be checked in the same manner.

Public: Documentation

Guzzler API

Guzzler API

General Usage Pattern:

Engine Open/Close

GuzzlerListDataSets

GuzzlerClose

GuzzlerGetLastError

Polygon Generation

GuzzlerBuildPolygons

GuzzlerGetPolygon

GuzzlerWritePolygons

Point-to-Point

GuzzlerXmlRequest

Input XML format:

Output XML format:

Meta Info

Description:

Example Input:

Example Output:

Guzzler – Usage Example

Resolving a Guzzler Data Set Specification

Home