Read Docs

Transcription

Read Docs

Drill Down Server® 4.5.2 Web
Services
Application Developer’s Guide
Release Date: October 15, 2010
Manual Version 1.0
The information in this document is PRIVILEGED & CONFIDENTIAL. It is intended solely for the use of authorized
recipients. If you are not the intended recipient, you are prohibited from reading, using, disseminating, distributing,
and/or copying this document.
deCarta, Inc. Confidential—Do not distribute without written consent from deCarta.
October 15, 2010
Headquarters:
Europe
APAC/China
Hong Kong
deCarta
4 North Second Street
Suite 950
San Jose, CA 95113
USA
Phone: +1 408 294 8400
Fax: +1 408 294 8464
deCarta
Gainsborough House
2 Sheen Road
Richmond
Surrey
TW9 1AE
United Kingdom
Phone: +44 208 973 2474
Fax: +44 208 973 2301
deCarta
Suite 2B, Shengyu
Building
185 Zhangjiang Road,
Pudong
Shanghai 201203
China
Phone: +86 21 5855
6100
Fax: +86 21 5855 6119
deCarta
Level 39
One Exchange Square
8 Connaught Place,
Central
Hong Kong
China
Phone: +852 2251 8431
Fax: +852 2251 8432
Sales Inquiries:
Technical Support:
[email protected]
Phone: +1 408 294 8400
[email protected]
Voice: +1 408 294 8400
Visit us at http://www.decarta.com
Legal Notice
Copyright © 2006, 2007, 2008, 2009, and 2010 by deCarta. All Rights Reserved.
deCarta, the deCarta logo, Drill Down Server, Rich Map Engine, and Traffic Manager are trademarks or registered
trademarks of deCarta, Inc. in the United States and/or other countries. All other company, brand and product names
are marks of their respective holders. This product or document is protected by copyright and distributed under the
terms of a license agreement, restricting its use, copying, distribution and decompilation (“License Agreement”). No
part of this document may be distributed without written consent from deCarta.
The product described in this document may be protected by one or more U.S. patents, foreign patents, or pending
applications. U.S. Patent Number 5,963,956 and 6,647,269. U.S. Patents Pending.
RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS
The documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is
subject to restrictions as set forth in the License Agreement and in subparagraphs (c)(1)(ii) of the Rights in Technical
Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial
Computer Software—Restricted Rights at 48 CFR 52.227-19, or their equivalent, as applicable. Manufacturer is
deCarta/Fourth North Second Street/Suite 950/San Jose, CA 95113.
DISCLAIMER OF WARRANTIES AND ACCURACY OF DATA
Although the information found on in this document is believed to be reliable, no warranty, expressed or implied, is
made regarding the accuracy, adequacy, completeness, legality, reliability, or usefulness of any information, either
isolated or in the aggregate. The information is provided "as is". All warranties of any kind, express or implied, including
but not limited to the implied warranties of merchantability, fitness for a particular purpose, and non-infringement of
proprietary rights, are disclaimed. Changes may be periodically made to the information by deCarta; these changes
may or may not be incorporated into this document.
ii
DDS Web Services Application Developer’s Guide
October 15, 2010
Contents
About This Manual
Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
How This Manual Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
CHAPTER 1
Introduction
1.1
DDS Web Services and OpenLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.1.1 Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2
Types of Access to DDS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.3
Architecture of Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.3.1 DDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.3.2 Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.3.3 Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.3.4 Operating Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.3.5 Service Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.3.6 Architecture Illustration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.3.7 Self-Hosted DDS Web Services with JavaScript API . . . . . . . . . . . . . . . . . 1-7
1.3.8 Hosted DDS Web Services with JavaScript API . . . . . . . . . . . . . . . . . . . . . 1-8
1.4
Documentation and Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
1.4.1 Summary of Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
1.4.2 Summary of Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
CHAPTER 2
2.1
2.2
2.3
The Developer Zone
Dev Zone Feature Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Signing up for the Dev Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Keep Track of Your IDs and Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2 Go to the Dev Zone and Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.3 Download, Download, Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.4 Familiarize Yourself with the Downloads . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.5 Try the Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.6 Test Your ID and Service Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.7 Execute Some XML Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.8 Experiment and Edit Sample XML Requests . . . . . . . . . . . . . . . . . . . . . . .
2-2
2-3
2-4
2-4
2-4
2-5
2-5
2-6
2-6
2-7
2-7
iii
October 15, 2010
2.3.9 Get Involved at the Forum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
2.4
Features of the Dev Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.4.1 Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.4.2 Forum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.4.3 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.4.4 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
2.4.5 The Web-based Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
2.4.5.1 Request Tester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
2.4.5.2 Driving Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
2.4.5.3 Geocoder FreeForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
2.4.5.4 Geocoder Structured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
2.4.6 The ClientWebApp Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
2.4.7 JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
2.4.7.1 Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
2.4.8 The Mythical Town of Stickville . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
CHAPTER 3
Deployment Options
3.1
deCarta Hosted DDS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
3.1.1 Using JavaScript API with Hosted Web Services . . . . . . . . . . . . . . . . . . . . 3-2
3.1.1.1 Using a Simple Proxy with JavaScript API . . . . . . . . . . . . . . . . . . . . . 3-3
3.1.1.2 AJAX Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.1.1.3 Using Dynamic Script Tags (JSON/GET). . . . . . . . . . . . . . . . . . . . . . 3-4
3.2
Self-hosted DDS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.2.1 Setup and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.2.1.1 Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.2.1.2 Setting Up DDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.2.1.2.1 License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.2.1.2.2 Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
3.2.1.2.3 Image Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
3.2.1.2.4 Projection Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
3.2.1.3 Setting Up Your Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.2.1.3.1 Connection to DDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.2.1.3.2 Configuring Image URL Path . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
3.2.1.3.3 Configuring for Image Host Aliases in Portray Requests . . . . . 3-9
3.2.1.3.4 Connection to the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
3.2.1.3.5 Configuring Aerial/Satellite Imagery . . . . . . . . . . . . . . . . . . . 3-10
3.2.1.3.6 In-Memory Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
3.2.1.3.7 Disk Based Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
3.2.1.3.8 Maximum Session IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
3.2.1.4 Setting Up Your Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
3.2.1.4.1 Setting Up POI Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
3.2.1.5 Setting Up DDS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
3.2.1.6 Supporting Wildcard Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
iv
October 15, 2010
3.2.2 Enabling DDS Web Services Fleet Services . . . . . . . . . . . . . . . . . . . . . . .
3.2.2.1 Verifying Fleet Services Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2.1.1 Database Diagnostic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2.1.2 Service Diagnostic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Setting up Apache Tomcat as a Windows Service . . . . . . . . . . . . . . . . . .
3.2.3.1 Before Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3.2 Installing Tomcat as a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3.3 Removing Tomcat as a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4.1 Starting DDS Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4.2 Logging Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4.2.1 Transaction and User Accounting . . . . . . . . . . . . . . . . . . . . . .
3.2.4.2.2 Maneuver Generation Debugging . . . . . . . . . . . . . . . . . . . . . .
3.2.5 Editing Image Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.1 Browser Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.2 Configuration for Online Image Settings Editor . . . . . . . . . . . . . . . .
3.2.5.2.1 Create Client Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.2.2 LibraryServlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.2.3 Modify service-configuration.xml With Editable Filename . .
3.2.5.3 Online Library of Image Settings . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.4 Starting the Image Settings Editor . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.4.1 Accessing the Image Settings Editor . . . . . . . . . . . . . . . . . . . .
3.2.5.4.2 Edit Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5.4.3 Smart Edit Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6 Image Cache Pre-Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6.1 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6.2 Setup and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6.3 Starting the Image Cache Pre-Renderer. . . . . . . . . . . . . . . . . . . . . . .
3.2.6.4 Using the Image Cache Pre-Renderer . . . . . . . . . . . . . . . . . . . . . . . .
3.2.7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.7.1 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 4
4.1
4.2
3-17
3-19
3-19
3-20
3-20
3-20
3-20
3-21
3-21
3-21
3-22
3-22
3-23
3-23
3-24
3-24
3-24
3-24
3-24
3-25
3-25
3-26
3-27
3-29
3-31
3-32
3-32
3-32
3-35
3-37
3-37
OpenLS Core Services and deCarta Extensions
XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Requests and Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.1 High Level View of Requests and Responses . . . . . . . . . . . . . . . . . . . . . . .
4.2.2 General XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2.1 xml version and XLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3.1 RequestHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3.1.1 clientName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3.1.2 clientPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3.1.3 sessionID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-2
4-4
4-4
4-6
4-6
4-7
4-7
4-7
4-7
4-8
v
October 15, 2010
4.2.3.1.4 configuration (deCarta extension) . . . . . . . . . . . . . . . . . . . . . . . 4-8
4.2.3.2 Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
4.2.3.2.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
4.2.3.2.2 requestID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.2.3.2.3 maximumResponses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.2.4 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.2.4.1 numberOfResponses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.2.4.2 Content-Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
4.3
Directory Service (POI Lookups) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
4.3.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
4.3.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
4.3.1.2 DirectoryRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
4.3.1.2.1 POILocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
4.3.1.2.2 POIProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
4.3.1.2.3 ReturnCountOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
4.3.1.2.4 freeformAddrLang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
4.3.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
4.3.2.1 DirectoryResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
4.3.2.2 POIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4.3.2.2.1 POI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4.3.2.2.2 Distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4.3.2.2.3 Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.3.3 deCarta Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.3.3.1 database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
4.3.3.2 Connection to External Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
4.3.4 POI Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
4.3.4.1 Multi-table External POI Database . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
4.4
Location Utility Service (Geocoding and Reverse Geocoding) . . . . . . . . . . . 4-23
4.4.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
4.4.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
4.4.1.2 GeocodeRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.4.1.2.1 Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.4.1.2.2 returnSpatialKeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.4.1.3 ReverseGeocodeRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.4.1.3.1 Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.4.1.3.2 streetNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
4.4.1.3.3 ReverseGeocodePreference . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
4.4.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
4.4.2.1 GeocodeResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
4.4.2.1.1 GeocodeResponseList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
4.4.2.1.2 GeocodedAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
4.4.2.2 ReverseGeocodeResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31
4.4.2.2.1 ReverseGeocodedLocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31
4.4.2.2.2 SearchCentreDistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
4.4.2.2.3 StreetAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
4.4.2.2.4 streetNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
vi
October 15, 2010
4.4.3 deCarta Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.3.1 Address locales: language + countryCode. . . . . . . . . . . . . . . . . . . . .
4.4.3.2 freeFormAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.3.3 parserReport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.3.4 parseOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.4 Geocoder Regex Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.5 Geocoder State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.5.1 Introduction to the Geocoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.5.2 report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.5.3 Structure and Organization of a Geocoder . . . . . . . . . . . . . . . . . . . .
4.4.5.4 The SimpleDemo Example Geocoder . . . . . . . . . . . . . . . . . . . . . . . .
4.4.5.5 Examples Using the SimpleDemo Geocoder. . . . . . . . . . . . . . . . . . .
4.5
Presentation Service (Drawing Maps) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1.2 PortrayMapRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.2.1 PortrayMapResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.2.1.1 Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.1 CenterAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.2 Pan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.3 Zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.4 Re-center Map (Screen Coordinates on Click) . . . . . . . . . . . . . . . . .
4.5.3.5 Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.6 Fit Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.7 Graphic Format Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.8 GridLayer and TileGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3.9 fixedgrid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6
Route Service (Calculate Routes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2 DetermineRouteRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.1 routeQueryType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.2 RoutePlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.3 distanceUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.4 RouteInstructionsRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.5 RouteGeometryRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.6 RouteMapRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1.2.7 RouteGeometryFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2.1 DetermineRouteResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2.1.1 StartAddressCandidates and EndAddressCandidates . . . . . . .
4.6.2.1.2 RouteSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2.1.3 RouteInstructionsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2.1.4 RouteGeometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-32
4-32
4-33
4-33
4-34
4-34
4-35
4-35
4-37
4-37
4-39
4-43
4-57
4-57
4-57
4-58
4-58
4-58
4-58
4-58
4-59
4-61
4-63
4-65
4-67
4-69
4-72
4-72
4-72
4-74
4-75
4-75
4-75
4-75
4-75
4-76
4-76
4-77
4-77
4-77
4-77
4-77
4-77
4-78
4-78
4-78
vii
October 15, 2010
4.6.2.1.5 RouteID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2.1.6 RouteMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.3.1 StartAddressCandidates, EndAddressCandidates . . . . . . . . . . . . . . .
4.6.3.2 RouteMapRequest Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.3.3 RouteInstruction Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.3.4 Route Finding Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.3.4.1 AlternateRoute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.4 Rules for Maneuver Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.4.1 RMAN-Based Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.4.1.1 Using Example Maneuver Rules Files . . . . . . . . . . . . . . . . . . .
4.7
Scrolling Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.1 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.1.2 ScrollRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.1.2.1 ScrollOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.1.2.2 ScrollType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.2.1 ScrollResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 5
4-78
4-78
4-79
4-79
4-80
4-82
4-82
4-83
4-83
4-84
4-85
4-91
4-91
4-92
4-92
4-92
4-92
4-92
4-92
OpenLS Fleet Services
5.1
Dispatch Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
5.1.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.1.2 DispatchRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.1.2.1 BestVehicleForJobRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.1.2.2 BestJobForVehicleRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.1.2.3 order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.1.2.4 useTraffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.1.2.5 ReturnManeuver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.1.1.2.6 AvoidList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.1.1.2.7 useTraffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.1.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.1.2.1 DispatchResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.1.2.1.1 BestJobForVehicleResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.1.2.1.2 BestVehicleForJobResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.2
Exclusion Zone Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.2.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.2.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.2.1.2 ExclusionZoneRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.2.1.2.1 ZoneCreateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.2.1.3 ExclusionZone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.2.1.3.1 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
viii
October 15, 2010
5.2.1.3.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.3.3 RestrictedActiveTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.4 ZoneUpdateRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.5 ZoneDeleteRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.6 ZoneRetrieveRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.6.1 ZoneRetrieveRequest return parameters . . . . . . . . . . . . . . . . .
5.2.1.6.2 ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.6.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.6.4 No Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1.7 DetermineRouteRequest with Exclusion Zones . . . . . . . . . . . . . . . .
5.2.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2.1 ExclusionZoneResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2.2 ZoneCreateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2.3 ZoneUpdateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2.4 ZoneDeleteResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2.5 ZoneRetrieveResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3
Geofencing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.2 GeofencingRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3 FenceCreateRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.1 RestrictedActiveTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.2 violationType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.3 returnViolationOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.4 FenceUpdateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.5 FenceDeleteRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.6 FenceRetrieveRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1.3.7 FenceViolationCheckRequest . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2.1 GeofencingResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2.1.1 FenceCreateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2.1.2 FenceUpdateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2.1.3 FenceDeleteResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2.1.4 FenceRetrieveResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2.1.5 FenceViolationCheckResponse . . . . . . . . . . . . . . . . . . . . . . . .
5.4
Route Compliance Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.1 methodName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2 RouteComplianceRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.1 RouteCreateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.2 RouteDeleteRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.3 RouteUpdateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.4 RouteRetrieveRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.5 Route Compliance Properties . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.6 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1.2.7 Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-11
5-11
5-12
5-12
5-13
5-13
5-14
5-14
5-14
5-14
5-15
5-15
5-15
5-16
5-16
5-16
5-18
5-19
5-19
5-19
5-19
5-20
5-20
5-20
5-20
5-21
5-21
5-21
5-22
5-22
5-22
5-22
5-22
5-22
5-23
5-24
5-24
5-25
5-25
5-25
5-26
5-26
5-26
5-27
5-27
5-28
ix
October 15, 2010
5.4.1.2.8 ComplianceCheckRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2.1 RouteComplianceResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2.1.1 RouteCreateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2.1.2 RouteDeleteResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2.1.3 RouteUpdateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2.1.4 RouteRetrieveResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2.1.5 ComplianceCheckResponse . . . . . . . . . . . . . . . . . . . . . . . . . . .
x
5-28
5-28
5-28
5-28
5-29
5-29
5-29
5-30
About This Manual
This manual describes version 4.5.2 of deCarta’s DDS Web Services, including use of
the Developer Zone.
Who Should Read This Manual
This manual is intended for software developers who develop applications using DDS
Web Services.
This manual assumes some rudimentary knowledge of XML. Greater familiarity with
XML and some familiarity with the OpenLS specifications will be helpful, but
numerous examples and sample applications will make it possible to work with DDS
Web Services while concurrently developing the additional knowledge that you might
need.
xi
October 15, 2010
How This Manual Is Organized
This manual contains the following chapters:
Chapter
Title
Purpose
1
Introduction
Provides an overview of DDS Web Services,
OpenLS, various architectures, and the
examples and documentation included with
DDS Web Services.
2
The Developer
Zone
Explains how to use the Developer Zone,
deCarta’s online site to help developers to
develop applications that use DDS Web
Services.
3
Deployment
Options
Explains how to deploy Hosted DDS Web
Services and Self-hosted DDS Web Services.
4
OpenLS Core
Services and
deCarta Extensions
Gives a summary and examples of the
OpenLS core services requests and responses,
with particular emphasis on deCarta’s
proprietary extensions to the OpenLS
specification.
5
OpenLS Fleet
Services
Gives a summary and examples of the fleet
based services requests and responses.
Conventions
This guide uses the following conventions to present information consistently, so that
it will be easier for you to use it:
Note: A note paragraph calls your attention to additional information about the
current subject, to important information, or to information that you might not
otherwise notice or expect.
Warning: A warning paragraph calls your attention to a potential pitfall that could
cause some sort of major malfunction, loss of data, or major performance degradation.
XML elements and attributes, code examples, code fragments,
language keywords, standard defined data types, function names,
filenames, and directory names appear in this font. However, if any
of these elements appear in a section heading, they are in the normal font. Examples:
<ns1:PortrayMapRequest zoom="0.4">
xii
October 15, 2010
clientPassword="yyyyy"
printf( "Hello, world." );
typedef struct{ double Lon, Lat; }RMF_POINT;
The RMF_POINT data type uses two floating point values, Lon and Lat, to
represent the longitude and latitude of a point.
See “RmfReaderNext()” on page 3-42 for details about the function
RmfReaderNext().
For presentation purposes, some examples of code may use the full width of
the page.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:XLS ns1:lang="en" version="1" xmlns:ns1="http://www.opengis.net/
xls">
Complete XML requests and responses may appear in figures. Example:
Figure 0.1. The Request/Response Elements of Directory Service Request/Response.
Directory01.xml example request
Directory01.xml example response
<ns1:Request methodName="DirectoryRequest" version="1.0"
requestID="10" maximumResponses="25">
<ns1:DirectoryRequest>
<ns1:POILocation>
<ns1:Nearest>
<ns1:Address countryCode="US">
<ns1:StreetAddress>
<ns1:Building number="225"/>
<ns1:Street>First St</ns1:Street>
</ns1:StreetAddress>
<ns1:PostalCode>11111</ns1:PostalCode>
</ns1:Address>
</ns1:Nearest>
</ns1:POILocation>
<ns1:POIProperties>
<ns1:POIProperty name="POIName" value="go-go"/>
</ns1:POIProperties>
</ns1:DirectoryRequest>
</ns1:Request>
<ns1:Response requestID="10" numberOfResponses="1" version="1.0">
<ns1:DirectoryResponse>
<ns1:POIContext>
<ns1:POI phoneNumber="+(1)-(631)-123-8910" ID="0"
POIName="GO-GO CAFE">
<ns2:Point xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>41.002 -72.0005</ns2:pos>
</ns2:Point>
<ns1:StreetAddress>
<ns1:Building number="(300 - 398), (301 - 399)"/>
<ns1:Street>2nd Ave</ns1:Street>
<ns1:Place type="CountrySubdivision">NY</ns1:Place>
<ns1:Place type="CountrySecondarySubdivision">SUFFOLK</
ns1:Place>
<ns1:Place type="Municipality">NEW YORK</ns1:Place>
</ns1:Address>
</ns1:POI>
<ns1:Distance uom="MI"
value="0.082190543709009009076815743810584535822272300720214843
75"/>
</ns1:POIContext>
</ns1:DirectoryResponse>
</ns1:Response>
Names of variables appear in italics. Example:
In the function prototype
void RmfReaderDestroy ( RMF_READER RmfRdr );
xiii
October 15, 2010
RmfRdr is a variable of type RMF_READER that you pass to the function
RmfReaderDestroy().
Italics may also be used to emphasize an important point. Example:
You do not have to calculate the map’s new center point; DDS Web Services
does that for you, based on the previous map’s center point and the panning
direction.
Clickable hypertext cross-reference links appear in blue text. You will see these in
PDF files of documentation. If you are using a black and white hard copy, you
probably will not notice any difference in this text. Example:
See “RmfReaderNext()” on page 3-42 for details about the function
RmfReaderNext(). The clickable link appears in blue.
Cross-reference links to Web sources appear in blue Courier font. Example:
You can see other examples by using the Client Web App at
http://ws.decarta.com:8080/clientwebapp.
xiv
October 15, 2010
Comments
If you have comments about this manual, please send them to the following address or
fax number:
deCarta
ATTN: Technical Publications
4 North Second Street
Suite 950
San Jose, CA 95113
Fax: +1 408 294 8464
xv
October 15, 2010
xvi
CHAPTER 1
Introduction
This manual describes the Drill Down Server® (DDS) Web Services software from
deCarta™ and the tools, documentation, and Developer Zone web site which are
available to help you to succeed in using DDS Web Services.
DDS Web Services is included as a standard part of DDS software for DDS
customers, and it is also available as a hosted web service for customers who want to
take advantage of the capabilities of DDS without the necessity of running, managing,
and administering DDS on their own servers.
1-1
October 15, 2010
DDS Web Services and OpenLS
1.1 DDS Web Services and OpenLS
DDS Web Services, which is deCarta’s implementation of Open GIS® Location
Service (OpenLS) Implementation Specification, enables rapid development of XMLbased location services applications. DDS Web Services uses the Drill Down Server as
a back-end server for location information.
OpenLS is an initiative of the Open Geospatial Consortium, Inc. (OGC). It is an open,
standards-based specification for XML-based location services over the Internet. This
implementation extends the OpenLS specification to include useful advanced features
which are beyond the standard OpenLS as well as some “preview” features which will
be included in future versions of OpenLS. XML schemas specify the format of valid
requests and of the responses returned
The DDS Web Services provides an XML-over-HTTP service interface. The Web
Service appears to the developer as a simple URL, to which you can post XML. The
service returns XML, containing URLs for images, and XML elements representing
addresses, routes, points of interest, and other structured information common to
location based services.
Note: DDS Web Services and OpenLS use XML requests and responses. However,
you don’t have to be an XML expert to understand and use this technology. We provide
a wealth of sample requests, tools to use and demonstrate the samples and the
responses they generate, and tools to experiment with varying the samples to learn.
You can quickly understand enough of the XML to use the schemas effectively and
adapt the samples to your own use.
Basic components such as elements and attributes of XML requests and responses are
discussed in “Requests and Responses” on page 4-4.
1.1.1 Functional Overview
DDS Web Services consists of the following core OpenLS services:
•
•
•
•
Directory Service (POI Lookup)
Location Utility Service (geocoding and reverse geocoding)
Presentation Service (map drawing)
Route Service (route calculation)
deCarta has extensions to each of these services.
1-2
Introduction
October 15, 2010
1.2 Types of Access to DDS Web
Services
Several types of access to DDS Web Services are available. These access types include
the following:
• The Developer Zone. The Developer Zone (often called “The Dev Zone” for short)
is a web site provided by deCarta for developers to learn about DDS Web Services,
to develop and test applications, and to participate in a community of developers
who all use DDS Web Services. Customers and prospective customers are eligible
to sign up to use the Dev Zone. Dev Zone membership includes access to a shared
instance of DDS Web Services, which you can use in developing and testing your
application.
• Hosted DDS Web Services. The Hosted DDS Web Services enables your web site
or application to provide DDS-based location services while avoiding the necessity
to deal with managing DDSs, geographic data, and related items on your own
servers. The Hosted DDS Web Services offers high availability and a variety of
service plans for commercial applications.
• Self-hosted DDS Web Services. DDS customers can run DDS Web Services on
their own servers. Your applications can use the XML-based web services interface
and can also directly access the DDS. The DDS Web Services is a standard part of
the DDS software package.
1-3
October 15, 2010
Architecture of Web Services
1.3 Architecture of Web Services
1.3.1 DDS
One or more DDSs run as backend servers for the DDS Web Services to process
geographic data and requests. At the Dev Zone and in Hosted DDS Web Services, the
DDSs run on deCarta’s servers. If you use Self-hosted DDS Web Services, the DDSs
run on your servers.
1.3.2 Web Service
The Web Service provides an XML-over-HTTP service interface. The web service
appears as a service URL (http://ws.decarta.com:8080/openls/openls) on
the Dev Zone or Hosted DDS Web Services. If you are using your own servers, the
URL has a similar form with your domain specified.
The web service receives XML requests from a client, generates one or more queries
to backend DDSs, receives responses from the DDSs, creates and formats an XML
response, and sends the response to the client.
Sometimes the web service must process initial responses from DDSs and then make
further queries to the DDSs before it can build the response to the client. For example,
in processing a routing request from the client, the web service might make one or
more queries to DDS to geocode the origin address, more queries to geocode the
destination, a query to calculate the route, additional queries to collect relevant
information about the route, and still more queries to create maps of the entire route
and of maneuvers along the route.
1.3.3 Client
Clients are typically a web browser or a Java application, but a client could be any
software capable of sending and receiving correctly formatted XML-over-HTTP
messages or using Dynamic Script Tags (DST) with JavaScript Object Notation
(JSON).
1-4
Introduction
October 15, 2010
When you register at the Dev Zone, you will be able to download various tools and
samples to help you to build your client. These aids include XML schemas, XML
sample requests, a sample web application, Java code samples that correlate with the
sample XML requests, and a JavaScript API. The deCarta JavaScript API can be used
in conjunction with Web Services, for accelerating development of draggable map
applications in browser-based environments. Dev Zone registrants also get access to a
web-based console that allows you to send sample XML requests (which you can edit)
to the Dev Zone server and examine the generated responses. Access to the web-based
console requires the client name and password which you receive when you register
for the Dev Zone. (If you use Self-hosted DDS Web Services, the web-based console
is available as a URL on your own server.)
1.3.4 Operating Principles
Your client application posts XML requests to the service URL. The service returns
XML responses. The format of the XML requests and responses is defined by the
XML for Location Services (XLS) schemas, including deCarta’s extensions to the
standard XLS schemas.
Every XLS request includes an outer XLS element (header information in a
RequestHeader element) plus a request element that depends on the type of request.
Responses have a similar structure.
The RequestHeader element contains clientName and clientPassword
attributes used for authentication.
1.3.5 Service Configurations
deCarta provides an extension to XLS to specify a service configuration name. Service
configurations can specify such information as which dataset to use for map drawing
and routing and the style of generated maps. On the Dev Zone, if a request does not
specify a service configuration, the request uses the Stickville sample dataset as a
default. See “The Mythical Town of Stickville” on page 2-27 for additional
information about Stickville.
Warning: If you attempt to view maps, perform geocodes, etc., and you have not set
the attribute configuration or use configuration=stickville you are likely
to see empty maps, or receive failed geocodes or other failures when you use realworld addresses or locations.
You can find more information about the service configuration available on the
Developer Zone in “Configurations” on page 2-10. You can find more information
1-5
October 15, 2010
about configuring DDS Web Services for Self-hosted DDS Web Services in “Setup
and Configuration” on page 3-5.
1.3.6 Architecture Illustration
This illustration shows the main functional elements of a Web Services application. Of
course, if you use Self-hosted DDS Web Services, the domain name is your domain
rather than decarta.com.
ws.decarta.com:8080 web server
DDS
OpenLS Servlet
XMLHTTPRequest
or
Dynamic Script Tags
(JSON/GET)
Your user
1-6
Your Application
Introduction
October 15, 2010
1.3.7 Self-Hosted DDS Web Services with
JavaScript API
The following illustration shows a Self-hosted DDS Web Services environment with
the deCarta JavaScript API. Web Services and JavaScript API use the proxy server
architecture by default. To configure your environment to use the Dynamic Script Tags
(JSON/GET) method, refer to the example titled “Getting Rid of Server of Origin (no
more XMLHTTPRequest)” found in the JavaScriptAPI/docs folder of the
software distribution package.
Customer Domain
DDS
Web Server
Customer Web
Application
OpenLS Web
Application
XMLHTTPRequest
Dynamic Script Tags
(JSON/GET)
deCarta JavaScript API
AJAX Application
1-7
October 15, 2010
1.3.8 Hosted DDS Web Services with JavaScript
API
The following illustrates a Hosted DDS Web Services environment with the deCarta
JavaScript API. Both a proxy server and Dynamic Script Tags (JSON/GET) method
are illustrated although the environment defaults to using a proxy server.
Hosted DDS Web Services
XMHTTPRequest
Customer Domain
Dynamic Script Tags
(JSON/GET)
Proxy
XMHTTPRequest
deCarta JavaScript API
AJAX Application
1-8
Introduction
October 15, 2010
1.4 Documentation and Examples
1.4.1 Summary of Documentation
The following table summarizes the documentation available to DDS Web Services
developers from the Documentation section of the Dev Zone:
Table 1.1. List of DDS Web Services and JavaScript API Documentation
Document(s)
Description
DDS_WebServices_AppDevGui
de_rev.pdf
DDS Web Services Application Developer’s Guide,
this manual.
USCartographicNT_ImageSet
tingConfiguration_DDSWS42
2.pdf
Describes the features of the supported image
settings configuration file for continental U.S.
NAVTEQ data.
Quick-Ref.pdf
A short reference guide to deCarta’s DDS Web
Services and Hosted Web Services.
Stickville-spec.doc
Describes and explains the fictional town of
Stickville, which is used as a simple example of
geographic information for learning to use DDS
Web Services.
XML schemas
XML schemas for the DDS Web Services, including
the core services, auxiliary schemas, and deCarta
schemas.
Javadocs
Javadocs for the provided Java API, for developing a
Java-based application that accesses DDS Web
Services. Note that this manual does not provide any
extensive explanation of the Java interface because
the Javadocs format will be more familiar and useful
to Java programmers.
JavaScriptAPI
Javadocs and “click-to-run” documentation.
1-9
October 15, 2010
Documentation and Examples
1.4.2 Summary of Examples
The DDS Web Services software package includes a rich set of example XML
requests that demonstrate the capabilities. For most of the XML examples, there is a
matching example of Java code that generates the same XML request and illustrates
the Java API.
The examples are all designed for use with Stickville. The following table lists and
describes the XML and Java examples:
Table 1.2. Sample Java Code and XML Example Requests
Java Sample
XML Sample
Description
Directory01.java
Directory01.xml
Find the POI with “go-go” in the name that is nearest
to a location. (Stickville has a POI named “Go-go
Cafe.”)
Directory02.java
Directory02.xml
Find the nearest POI that is a restaurant.
Directory03.java
Directory03.xml
Find all POIs within a distance of an address.
Directory04.java
Directory04.xml
Find POIs in an external database.
n/a
Directory05.xml
Uses freeformAddrLang attribute.
Dispatch01.java
Dispatch01.xml
Calculates distance and ETA to determine best vehicle
for job (positioned task).
Dispatch02.java
Dispatch02.xml
Calculates best job for vehicle.
Dispatch03.java
Dispatch03.xml
for job using traffic data in calculating distance and
ETA.
Dispatch04.java
Dispatch04.xml
for job using an avoid features type list.
ExclusionZone01.
java
ExclusionZone01.
xml
Create a POLYGON exclusion zone.
ExclusionZone02.
java
ExclusionZone02.
xml
Create a CIRCLE exclusion zone.
ExclusionZone03.
java
ExclusionZone03.
xml
Create a LINE exclusion zone.
ExclusionZone04.
java
ExclusionZone04.
xml
Retrieve all exclusion zones.
ExclusionZone05.
java
ExclusionZone05.
xml
Retrieve an exclusion zone with zone ID.
ExclusionZone06.
java
ExclusionZone06.
xml
Retrieve exclusion zones with zone properties.
1-10
Introduction
October 15, 2010
Table 1.2. Sample Java Code and XML Example Requests (Continued)
Java Sample
XML Sample
Description
ExclusionZone07.
java
ExclusionZone07.
xml
Update an exclusion zone with zone ID.
ExclusionZone08.
java
ExclusionZone08.
xml
Delete an exclusion zone with zone ID.
ExclusionZone09.
java
ExclusionZone09.
xml
Batch-create/bulk-load exclusion zones.
Geocode01.java
Geocode01.xml
Geocode a structured street address.
Geocode02.java
Geocode02.xml
Batch geocode three street addresses, one of which is a
freeform style address. The other two are structured
addresses.
Geocode03.java
Geocode03.xml
Uses the returnSpatialKeys attribute by returning
spatial keys to addresses in a local database.
Geocode04.java
Geocode04.xml
Uses the parserReport and parseOnly attributes
by returning a structured address from a freeform
address entered by a user.
Geofencing01.jav
a
Geofencing01.xml
Creates a polygon geofence with geofence properties
and restricted day and time restrictions.
Geofencing02.jav
a
Geofencing02.xml
Creates a circular geofence with geofence properties
and restricted day and time restrictions.
Geofencing03.jav
a
Geofencing03.xml
Retrieves all geofences.
Geofencing04.jav
a
Geofencing04.xml
Retrieves a geofence using a geofence ID.
Geofencing05.jav
a
Geofencing05.xml
Retrieves geofences using geofence properties.
Geofencing06.jav
a
Geofencing06.xml
Updates a geofence with a geofence ID.
Geofencing07.jav
a
Geofencing07.xml
Deletes a geofence with a geoence ID.
Geofencing08.jav
a
Geofencing08.xml
Bulk loads geofences from a file.
Geofencing09.jav
a
Geofencing09.xml
Performs a geofence violation check with the location
of check points.
Geofencing10.jav
a
Geofencing10.xml
Performs a geofence violation check with the location
and date/time of check points.
Map01.java
Map01.xml
Get a URL to a GIF map of Stickville.
1-11
October 15, 2010
Java Sample
XML Sample
Description
Map02.java
Map02.xml
Get a BASE64-encoded JPG map of Stickville.
Map03.java
Map03.xml
Get a URL to a GIF map of Stickville with icons and
text overlaid.
Map04.java
Map04.xml
Request a URL to a map that has a picture of a
simulated geofence, and two icons.
Map05.java
Map05.xml
Make a series of four requests to the server for map
URLs. The first two requests zoom out, the second two
requests pan north-east. Map05.xml is the first “zoom
out” request sent to the server. (Demonstrates deCarta
proprietary features.)
Map06.java
Map06.xml
Uses the fitOverlays attribute to automatically
stretch the map to include all icon overlays.
(Demonstrates a deCarta proprietary feature.)
Map07.java
Map07.xml
Uses the CenterAddressType. Demonstrates a
deCarta proprietary feature. Also demonstrates use of
FreeFormAddress.
Map08.java
Map08.xml
Uses the CenterAddressType in conjunction with a
Style Overlay, to place an icon and text in the center of
the map. (Demonstrates deCarta proprietary features.)
n/a
Map09.xml
Demonstrates use of TileGrid to obtain URLs to
map tiles, for the purpose of making a draggable tiled
AJAX map. (Demonstrates deCarta proprietary
features.)
n/a
Map10.xml
Demonstrates use of Pan elements inside of
TileGrid element. (Demonstrates deCarta
proprietary features.)
n/a
Map11.xml
Demonstrates overlay of RouteGeometry on top of
tiles.
n/a
Map12.xml
Demonstrates how to affect various graphical format
parameters such as image quality and compression
levels.
n/a
Map13.xml
Demonstrates how to use the TileGrid element to
request GlobeXplorer imagery.
n/a
Map14.xml
Demonstrates the use of server-side shape rendering.
n/a
Map15.xml
Demonstrates dynamic image settings such as pointing
the SETTINGS attribute to a URL that pulls up a new
image settings file after authentication.
1-12
Introduction
October 15, 2010
Java Sample
XML Sample
Description
n/a
Map16.xml
Demonstrates fixed tile grid and in-memory cache.
n/a
POISchemaExample
.xml
Demonstrates an XML mapping file which conforms
to POISchema.xsd to allow directory requests
access to an external POI database.
ReverseGeocode01
.java
ReverseGeocode01
.xml
Performs a basic reverse geocode.
n/a
ReverseGeocode02
.xml
Reverse geocodes to street address and reports
distance from the input point to the address.
n/a
ReverseGeocode03
.xml
Reverse geocodes to nearest intersection, and reports
distance to the intersection.
Route01.java
Route01.xml
Calculates a route and gets human-readable turn-byturn route instructions.
Route02.java
Route02.xml
Gets human-readable turn-by-turn route instructions,
route geometry, an overview map, and maneuver
maps.
Route03.java
Route03.xml
Request a “route handle,” which can be provided in
subsequent map requests. Route03.xml shows only
the request for the handle, Route03.java issues a
subsequent route request using the handle.
Route04.java
Route04.xml
Uses a Position and Point as a route WayPoint.
Route05.java
Route05.xml
Requests different dimensions for overview and
maneuver maps.
Route06.java
Route06.xml
Requests only an Overview map (no maneuver maps).
n/a
Route07.xml
Multi-point routing example (uses waypoints).
n/a
Route08.xml
Multi-point routing example (uses waypoints). Shows
restaurants, gas stations, and waypoint icons on the
overview and maneuver maps. Also allows for
selecting maneuver-rules file.
n/a
Route09.xml
Same as Route08.xml, but shows driving directions
in French.
n/a
Route10.xml
Uses routeQueryType set to RMAN, so routing uses
the DDS Routing Plug-in query RMAN for determining
the route.
n/a
Route11.xml
Uses the orientation attribute for maneuver maps.
n/a
Route12.xml
Demonstrates requesting a BoundingBox, Point and
Geometry.
1-13
October 15, 2010
Java Sample
XML Sample
Description
n/a
Route13.xml
Optimized multi-point routing example. Uses pregeocoded latitudes and longitudes (the preferred
method) for waypoints instead of embedded freeform
addresses.
n/a
Route14.xml
Requests alternate route be returned in addition to
requested route.
RouteCompliance0
1.java
RouteCompliance0
1.xml
Creates a route compliance using LineString.
RouteCompliance0
2.java
RouteCompliance0
2.xml
Creates a route compliance using Base64 encoded
RouteID.
RouteCompliance0
3.java
RouteCompliance0
3.xml
Retrieves all route compliances.
RouteCompliance0
4.java
RouteCompliance0
4.xml
Retrieves a route compliance using a route compliance
ID.
RouteCompliance0
5.java
RouteCompliance0
5.xml
Retrieves route compliances using routecompliance
properties.
RouteCompliance0
6.java
RouteCompliance0
6.xml
Updates a route compliance using a route compliance
ID.
RouteCompliance0
7.java
RouteCompliance0
7.xml
Deletes a route compliance using a route compliance
ID.
RouteCompliance0
8.java
RouteCompliance0
8.xml
Checks a route compliance violation using a
transmitted route.
RouteCompliance0
9.java
RouteCompliance0
9.xml
Checks a route compliance violation check using a
saved route.
n/a
Scroll01.xml
Uses ScrollRequest to demonstrate the scrolling
service feature for street names.
n/a
Scroll02.xml
Uses ScrollRequest to demonstrate the scrolling
service feature for city names.
StatefulClient01
.java
n/a
Uses PortrayMapRequest to establish stateful
session.d
1-14
CHAPTER 2
The Developer Zone
The Developer Zone is an online service that enables developers to quickly prototype
and develop location-enabled applications. Developers can write applications that
make LBS queries to a shared DDS via the Internet. Developers can sign up, access
documentation, download software and various tools, get support and manage their
account at http://developer.decarta.com.
One of the main advantages of the Developer Zone is faster development time.
Developers can develop a proof of concept application in about an hour and a working
application in a day. Application developers do not have to worry about some of the
more complex aspects of deploying the DDS, such as updating of geographic datasets,
DDS cluster administration, etc. This hosted service is intended for prototyping and
pre-production development only. It is offered at no cost to qualified developers.
We frequently refer to the Developer Zone as the “Dev Zone” for short. Most
references in this manual use the shorter, more informal name.
2-1
October 15, 2010
Dev Zone Feature Summary
2.1 Dev Zone Feature Summary
The following are some features of the Dev Zone that help to make it a valuable
resource for developers in learning to use DDS Web Services and in developing
applications using DDS Web Services:
• Downloads of software, examples, and documentation. For more details, see
“Downloads” on page 2-9.
• Forum, a discussion forum for developers, sometimes including deCarta’s Web
Services developers. See “Forum” on page 2-9.
• FAQ, a summary of frequently asked questions. See “FAQ” on page 2-9.
• Several map display configurations which show the map styles available for Hosted
DDS Web Services and which may give you starting ideas for your own map
displays if you will use Self-hosted DDS Web Services. See “Configurations” on
page 2-10.
• Data configurations, including Stickville. When you sign up the Dev Zone you
choose one commercial data vendor’s data to use on the Dev Zone. Additionally, all
Dev Zone users can use the sample mythical town of Stickville. See
“Configurations” on page 2-10 and “The Mythical Town of Stickville” on page
2-27.
• The Web-based Console, a sample application that enables you to experiment with
the provided sample XML requests, with routing calculations and displays, and
with structured and freeform geocoding. If you will use Self-hosted DDS Web
Services, you can also adapt its administration features for your own use. See “The
Web-based Console” on page 2-13.
• ClientWebApp sample application, another sample application that was designed
to make it easy to see request and response XML for maps and routes, including
some of deCarta’s proprietary extensions to the OpenLS presentation service (map
drawing). See “The ClientWebApp Sample Application” on page 2-25.
• JavaScript API, deCarta’s JavaScript API for developing web-based mapping
applications using Object Oriented JavaScript to provide modular fluid maps,
panning, zooming, geocoding, reverse geocoding, routing, pin overlays, with
street/hybrid/satellite views.
• Online Repository of Image Settings for Self-hosted DDS Web Services, provides
an online area where image settings are placed, read, and written. You can edit
image settings in real-time, in conjunction with DDS functionality of reading
image settings from a URL. See “Operation” on page 3-21.
2-2
The Developer Zone
October 15, 2010
2.2 Signing up for the Dev Zone
You must register for the Dev Zone before you can use its features. To register, go to
http://developer.decarta.com (or click the Developers tab on the deCarta
homepage http://www.decarta.com) and click the “Sign Up” button. Fill out and
submit the registration form.
When your registration is approved, you will receive an email with further
instructions. This email includes your clientName and clientPassword, which
are required to login to the Web-based Console sample application and are required in
all XML requests sent to the Dev Zone. (However, when you use the Web-based
Console, it automatically inserts them into requests that you generate there.) Note that
this ID and password are not the same email address and password that you use to sign
in at http://developer.decarta.com to use Dev Zone features other than
sending requests to DDS Web Services.
Go back to the Dev Zone at http://developer.decarta.com, login, and start
downloading and experimenting!
2-3
October 15, 2010
Getting Started
2.3 Getting Started
After you register and receive your confirmation, you’ll want to get started quickly.
What to do first? The short answer is login, download, and start experimenting. But
you probably want something more specific than that. The following sections give
some suggestions for first steps in getting started.
2.3.1 Keep Track of Your IDs and Passwords
You have two different IDs and associated passwords to use on the Dev Zone:
• Your Dev Zone login—the email address that you used when you registered for the
Dev Zone and the password that you chose during the registration process. You use
these to login to the Dev Zone at http://developer.decarta.com to get
downloads, obtain documentation, participate in the developer forum, and to see
what’s new.
• Your clientName and clientPassword, which you use to login to the Webbased console and which you must include in XML requests that you compose to
send to the Dev Zone. (In most cases, the sample applications automatically
include those, so you don’t have to. But as you develop your own application, you
will need to include them in requests that your application makes.) Your
clientName and clientPassword are included in the confirmation email that
you received when you registered for the Dev Zone.
2.3.2 Go to the Dev Zone and Login
An obvious step to take, but you’ll have to do it before trying to do the following steps.
Set your browser to the Dev Zone (http://developer.decarta.com) and login.
For all activities on the Dev Zone, Internet Explorer is the preferred and tested
browser.
2-4
The Developer Zone
October 15, 2010
Figure 2.1. Login Window for Dev Zone
2.3.3 Download, Download, Download
Download the client software distribution (from the Download tab). Download any
documentation that sounds useful from the Documentation tab. If you will be
developing in Java, you’ll probably want to download the Java sample application
from the Download tab.
Note that when you go to the Download tab, you will be required to agree to the user
agreement.
Unzip any zipped files, using any standard unzip utility.
2.3.4 Familiarize Yourself with the Downloads
We suggest that you browse around your downloads to become familiar with all that is
there. In particular, you will probably want to find the following files and directories
in the client software distribution:
• docs/api. A subdirectory under docs, which contains all the Java API
information.
• docs/xml-schema. A subdirectory under docs, which contains all the XML
schemas. You probably won’t want to delve into the schemas too deeply initially,
until you become somewhat familiar with them by using the example XML and the
sample applications. Later when you become more sophisticated and
2-5
October 15, 2010
Getting Started
knowledgeable, you will refer to the schemas to learn about all the rich possibilities
of OpenLS and deCarta’s extensions to OpenLS.
• test_XML. This directory contains all the pre-prepared sample XML queries,
which illustrate many of the capabilities of all four core services.
• obj and src. These directories contain sample Java source and object code that
will generate XML requests that correspond to many of the XML sample requests
in test_XML. You can use the file names to correlate Java files with XML samples.
2.3.5 Try the Sample Applications
Try using the Web-based Console and the ClientWebApp sample applications. For
more details about these samples refer to “The Web-based Console” on page 2-13 and
“The ClientWebApp Sample Application” on page 2-25.
To quickly try out these sample applications, use the following URLs in your browser:
• Web-based Console: http://ws.decarta.com:8080/openls/console.
You’ll have to login to each tab separately to use it. You use your clientName and
clientPassword here.
• ClientWebApp: http://ws.decarta.com:8080/clientwebapp. You can use
the demo login here (It appears by default when you open the URL) or use your
own clientName and clientPassword.
2.3.6 Test Your ID and Service Configuration
You can test that your clientName and clientPassword are activated by logging
on to the Request Tester tab. If the login succeeds, then they are activated. Use the
Browse tab to find one of the sample XML requests in the test_XML directory. When
you select it, the XML appears in the request section of the browser window.
However, if you look closely at the XML there, you will find that in the
RequestHeader, the application has substituted your clientName and
clientPassword for the dummy names in the sample files. Click the
execute request button, and the response appears in the response section of the
window.
Use the Driving Directions tab of the Web-based Console to verify your service
configuration. When you login to that tab, the service configuration selection
area will show several names of service configurations. The first is Stickville,
which uses the Stickville dataset and a default map display configuration. The next
selection in the list will have the data vendor’s name that you chose when you
registered for the Dev Zone. Additional service configuration names may show
2-6
The Developer Zone
October 15, 2010
alternative map display formats and additional map data areas, such as North America
and Europe.
While you are looking at the Driving Directions tab, you may also notice a selection
box for “locales.” A locale is a deCarta extension of OpenLS which specifies a
combination of a country and language. You may have to make a selection in that box
to get a successful test of your ID and configuration. To find more information about
locales, please refer to “Address locales: language + countryCode” on page 4-32.
2.3.7 Execute Some XML Requests
On the Request Tester tab of the Web-based Console, use the Browse button to
browse to various of the sample XML requests and execute the requests. Begin to
familiarize yourself with the responses.
One idea that you might want to try is to execute each of the sample XML requests
and save the resulting response in a file so that you can look at them all more closely
with a text-viewing tool such as Notepad or Wordpad or with an XML-viewing tool.
The saved responses can be a useful reference.
2.3.8 Experiment and Edit Sample XML
Requests
Finally, in your initial exploration of the Dev Zone tools, you’ll soon want to start
experimenting with editing the canned XML samples.
Try changing the input parameters and see the resulting different responses. Put in
obviously erroneous input and see what error responses look like. Where the samples
use mythical Stickville addresses, try using real-world addresses (and of course, use
one of the real-world configuration names).
If you have any problems with XML, it might be helpful to use an XML validator
locally, to validate XML requests against the XML schemas. A good XML validator
will give more precise information about any problems with the XML structure than
the error returned by the web-based console. If you validate locally, your XML editor
may require that you add an xsi:schemaLocation attribute to the XML; however,
when you send the XML to DDS Web Services, you should not include that attribute.
Warning: If you attempt to view maps, perform geocodes, etc., and you have not set
the attribute configuration or use configuration=stickville, you are likely
to see empty maps, or receive failed geocodes or other failures when you use realworld addresses or locations.
2-7
October 15, 2010
Getting Started
2.3.9 Get Involved at the Forum
Sooner or later, and probably sooner, you’ll want to start checking out the developer
forum on the Forum tab of the Dev Zone. You’ll find a wide variety of topics there
from simple help for newbies just getting started to esoteric discussions of advanced
topics, and ranging over all the core services, how to use the site, documentation
issues, and requests for and feedback about new features. If you’re having a problem,
perhaps someone else already had the same problem and will help you get past it more
quickly than they did.
2-8
The Developer Zone
October 15, 2010
2.4 Features of the Dev Zone
The Developer Zone web site is http://developer.decarta.com. You will have
to register for a Dev Zone account and login to use most features of the Dev Zone. At
the Dev Zone you can read the latest news about the Dev Zone itself as well as about
deCarta, participate in a developers’ forum for Dev Zone developers, and download
various documentation and training helps.
2.4.1 Downloads
The Dev Zone has software, examples, and documentation available for download. All
the examples discussed throughout this manual are available at the Dev Zone.
Examples, documentation, and sometimes new prototype features are updated more
frequently than we do formal releases of products, so you should check the download
area of the Dev Zone periodically for new information.
2.4.2 Forum
The Dev Zone has a discussion forum which is available to all registered users of the
Dev Zone. New and experienced Dev Zone developers use the forum to ask questions,
share experiences and learning, and help each other. deCarta developers and support
personnel also occasionally check in at the forum.
Some of the kinds of topics discussed on the forum include these: help for new users
getting started, discussion of the sample applications, discussion about features of Dev
Zone and DDS Web Services, JavaScript API, maintenance, and new features.
2.4.3 FAQ
The Dev Zone has a summary of frequently asked questions covering a range of topics
including broad questions and product-specific questions.
2-9
October 15, 2010
Features of the Dev Zone
2.4.4 Configurations
A number of configurations are available for Dev Zone users. A configuration consists
of a dataset and a map display format. (Experienced DDS users may recognize these
configuration elements as part of the DDS configuration file.)
All registered users have access to the Stickville dataset and its default map display
configuration. Each user chooses one “real life” dataset at registration time; currently
datasets from Tele Atlas and NAVTEQ are available for North America and Europe,
but the available datasets can change.
Several map display configurations are available to use in conjunction with the real
earth datasets. You can change the selected map display configuration from request to
request (by using the configuration attribute, which is described elsewhere in this
manual), but you can not change your available real earth dataset. deCarta
occasionally changes the available map display configurations, typically by adding a
new one.
Here is a summary of some of the configurations available on the Dev Zone. On the
Driving Directions tab on the Web-based Console, you can choose the service
configuration from the drop down list. There are now significantly more
configurations than appear in this list, and additional ones are periodically added. In
particular, some European data is now available on the Dev Zone. Each setting has a
corresponding “-tile” setting for use in tiled, draggable maps. Note that the sample
map images have been reduced in size to fit the table:
Table 2.1. Partial List of Configurations with Sample Map Images
Configuration
Name
Stickville
2-10
Data
Coverage
Area
the
imaginary
town of
Stickville
Map Display
Configuration
Sample Map Image
Uses the DDS
default image
configuration
The Developer Zone
October 15, 2010
Table 2.1. Partial List of Configurations with Sample Map Images (Continued)
Configuration
Name
Data
Coverage
Area
teleatlas-northamerica
California
blue-steel
California
old-english
California
Map Display
Configuration
Sample Map Image
2-11
October 15, 2010
Configuration
Name
Data
Coverage
Area
navteq-northamerica
North
America
blue-steel
North
America
old-english
North
America
2-12
Map Display
Configuration
Sample Map Image
The Developer Zone
October 15, 2010
Configuration
Name
US-Carto-NT
Data
Coverage
Area
Map Display
Configuration
Sample Map Image
North
America
Note: To avoid image misalignments and pin drifts using DDS 4.1.3 sp03 (or later)
Web Services or DDS 4.1.3 sp03 (or later) JavaScript API, the Projection
parameter of the DDS configuration file (ddserver.cfg) and image settings files
must be set to MERCATOR_ELLIPSOIDAL.
2.4.5 The Web-based Console
The Web-based Console provides a way for you to execute the provided sample XML
requests, to test your own requests, to experiment with changing requests, plus a tabbased interface to see and experiment with several specific OpenLS core services.
You can access the Web-based Console at http://ws.decarta.com:8080/
openls/console. You should use Internet Explorer to use it.
2-13
October 15, 2010
When you access the Web-based Console, you will see a screen similar to this one:
Sometimes new features are added to the sample applications, and other
enhancements or changes may occur, so it is possible that what you see does not
exactly match this view.
Each tab is the access point to a different feature, and each tab requires its own
separate login. Additionally, the tabs timeout when not used, so after a period of
inactivity, you may have to login again. The tabs provide the following functions:
• Request Tester—compose (or load) a request, execute it, and see the XML
response.
• Usage Reporting—generate usage information for the DDS Web Services site
(administrator-only function).
• Cache—monitor and control the cache of map images (administrator-only
function).
• Driving Directions—calculate a route, display an overall map of the route, and
display instructions and small maps for each maneuver along the calculated route.
• Geocoder FreeForm—use the FreeForm Geocoder to parse and geocode a freeform
address.
• Geocoder Structured—use the structured geocoder to geocode a structured address.
In a structured address, each address element appears separately. For example, for
the address “4 N. 2nd St., San Jose, CA 95113 USA,” there are six separate
structured address elements: street number (“4”), street name (“N. 2nd St.”), city
(“San Jose”), state (“CA”), postal code (“95113”), and country (“USA”).
• Admin—various administrative functions (administrator-only function).
The tabs denoted by “(administrator-only function)” are for administrators only, so
you will not be able to use those tabs on the Web-based Console at the Dev Zone. If
you license the Drill Down Server to run Self-hosted DDS Web Services, you will be
able to set up the configuration file to allow you access to those tabs.
On each tab, you must login in using your clientName and clientPassword.
Before you login, each tab looks the same as the Request Tester tab, displaying
the logic screen. Obviously, all the tabs take on very different looks after you login.
The following sections explain how to use each non-administrator tab.
2-14
The Developer Zone
October 15, 2010
2.4.5.1 Request Tester
After you login to the Request Tester tab, a screen such as this one appears:
The request section of the screen is where you can create an XLS request. You can
create the request in any of several ways: paste a request into the request area from
the clipboard, compose a request directly in that area, use Browse in the upper area of
the screen to browse your computer for a file containing an XML request and have it
pasted into the request area, or type a filename in the text box and select Send.
If you use the browse button to find a file, when you select the file, the console pastes
that file into the request area. When you use Browse or Send to select one of the
sample XML requests, the console substitutes your clientName and
clientPassword for the dummy placeholders in the sample files.
2-15
October 15, 2010
After you have a request in the request area, select execute request to send the
request to DDS Web Services. The response then appears in the response area of the
window. At that time, the window will appear similar to this one:
The request and response areas do not use word wrap, so you may have to use the
scroll bars to see full lines of the requests or responses. When a request throws an
exception, the response pane displays the full XML containing Error elements.
You can use Browse again to load a new file into the request area. When you do so,
the content of the response area does not change until you select
execute request.
2-16
The Developer Zone
October 15, 2010
2.4.5.2 Driving Directions
When you login to the Driving Directions tab, you initially get a screen similar
to this one:
The parameters initially have Stickville values set and the Stickville service
configuration selected. Since this tab of this sample application is somewhat
minimalist, it doesn’t have a full geocoder and requires a postal code to find the origin
and destination.
To use the DDS RMAN query to generate the route and driving direction, select the
check box for RMAN rule file. The RMAN rule file check box is displayed in
the following screen shot:
2-17
October 15, 2010
For more information on using the RMAN rules file to generate routes, refer to
“DetermineRouteRequest” on page 4-75 and “Rules for Maneuver Generation” on
page 4-83.
2-18
The Developer Zone
October 15, 2010
When you select get directions, the application calculates the route and generates
maps and driving directions in the lower part of the browser window. The display is
similar to this one:
The larger map at the top, below the label Overview, shows an overview of the entire
calculated route. The map’s style is determined by the service configuration
that you selected; for the Stickville service configuration, the map style is always the
DDS default style.
2-19
October 15, 2010
The next, usually larger section, of the display is a table which shows information and
a map for each maneuver along the route. The maneuver maps are each smaller than
the overview map. The table shows the following information for each maneuver:
Table 2.2. Driving Directions Tab’s Table of Route Maneuvers
Column
Heading
Meaning
Distance
The travel distance from the maneuver’s starting point
(previous maneuver point or the origin, for the first
maneuver) to the point of this maneuver. This sample
application shows the distance in miles; of course, your real
application may use other units.
Duration
Duration is the travel time for this maneuver, from the
starting point to the maneuver point. The data format used
here is the raw data format for the duration attribute of the
RouteInstruction element. For example, the information
in the first maneuver P0DT0H0M45S is interpreted to mean
0 days, 0 hours, 0 minutes, 45 seconds for the time to
complete the maneuver. Obviously, your real
application will probably interpret this data rather than
showing the raw data format.
Maneuver
This is the text from the Instruction element nested in the
RouteInstruction element. The text is produced by the
DDS RTXT query, using the default maneuver rules file that
comes with the DDS software. If you want more information
about that, please refer to the Drill Down Server Reference
Manual.
Maneuver Map
A small map showing the maneuver.
Both the overview map and the maneuver maps highlight the route.
You may find it useful to compare and correlate information in the Driving
Directions tab with information in the Request Tester tab for the same
calculated routes. For example, the initial default parameters on the Driving
Directions tab are almost identical to the parameters in the Route01.xml sample
request, which you can easily run on the Request Tester tab; the street numbers
are slightly different, but otherwise the origins and destinations are the same.
After you do a route calculation, a string is displayed at the bottom left of the browser
window, below the table of maneuvers. The string does not appear to be meaningful to
human reading. It typically looks something like this: 11514ecf:10969bb17f0:7fce. This string is the “route handle.” Your application can remember this route
handle and later retrieve information about the route without completely re-calculating
the route.
2-20
The Developer Zone
October 15, 2010
For example, in the Driving Directions tab, you can copy a previously-obtained route
handle into the field get directions from handle and click the
get directions from handle button, and the previously calculated route
information and maps will appear, without re-geocoding the origin and destination, recalculating the route, or re-generating the maps. Route handles and the maps
associated with them are not permanent and will eventually disappear from the
server’s cache.
2.4.5.3 Geocoder FreeForm
The Geocoder FreeForm tab uses freeform geocoding. freeform geocoding parses
an address into meaningful tokens so that your application doesn’t have to parse it or
require your users to manually parse their address information into separate data
entries.
When you login to the Geocoder FreeForm tab, you see a display similar to the
following:
2-21
October 15, 2010
To proceed, select a service configuration and a country-language combination, enter
a freeform address, and click execute geocode. The application fills in the
request section of the display with the XML request that it generated and fills in the
response section with the XML response returned from DDS Web Services. The
display then looks similar to the following:
The freeform geocoding’s address format is very flexible and uses multiple strategies
to try to find a good match for the address, even when parts of the address are missing
or incorrect. If you look closely at the generated response, you will find details about
which strategy yielded the found answer, how good the match was, and even the
specific DDS query that resulted in a match.
2-22
The Developer Zone
October 15, 2010
If you select the return freeform address checkbox, the response includes a
freeFormAddress which may have more or different detail than the input
information. For example, in this case the input intersection was “2nd & santa clara”
but the response provides more detailed information: “N 2ND ST AND E SANTA
CLARA ST”. If you do not select the return freeform address checkbox, the
response includes various geographic subdivisions appropriate for the location, such
as city and county.
In a Self-hosted DDS Web Services environment, the structure and formatting of
returned freeform addresses is configurable. To learn more details about the freeform
geocoder, see “freeFormAddress” on page 4-33 and “GeocodeMatchCode” on page
4-26.
2.4.5.4 Geocoder Structured
The Geocoder Structured tab uses the standard OpenLS geocoding technique in
which each address piece appears in the request as a separate element. For example,
building number, street name, city, and postal code are all separate elements. To use
this method of geocoding, your application must either parse the elements from a
user’s input or require the user to enter each element separately.
2-23
October 15, 2010
When you login to the Geocoder Structured tab, a display similar to the
following appears:
Initial default values are filled in. You can change them. If you choose to simply use
the defaults to get started, you may have to make a selection for country and language
codes because a default may not be selected.
When you select execute geocode, the application fills in the request XML and the
response XML in the request and response areas of the window. The request
and response areas are like the same areas on the Request Tester tab. If you want
to experiment with making changes to the XML in the request area, you should
copy it to another location (for example, the request area on the Request Tester
tab) because when you select execute geocode again, the request area will
change to show the request based on whatever parameters are currently specified on
this tab.
2-24
The Developer Zone
October 15, 2010
2.4.6 The ClientWebApp Sample Application
The ClientWebApp sample application provides a way for you to see and experiment
with XML requests and responses, particularly for mapping and routing functions.
deCarta provides the Java source code for this reference application, available for
download from the Dev Zone.
A particularly useful aspect of this sample application is that it demonstrates deCarta’s
proprietary extensions to the OpenLS presentation service (map drawing). These
extensions include capabilities to make it easy to develop an application that has
familiar mapping features such as zooming in and out, re-centering the map, and using
panning directional arrows.
To access the ClientWebApp without compiling it from source, simply point your
browser to http://ws.decarta.com:8080/clientwebapp. The initial screen
requires a login; however, you can use the pre-set demo login.
When you login, the initial screen allows you either to create a map centered at an
address or to calculate a route from an origin to a destination and get a map of the
route. The initial screen looks like the following:
2-25
October 15, 2010
After you fill in the required information and make a query, the gray square on the
right side is replaced with an appropriate map, and two new command buttons are
displayed below the map: Show Request XML and Show Response XML. The
screen looks similar to the following:
You can click Show Request XML or Show Response XML to see the XML for the
request for the last action you took or the XML response to your action.
2.4.7 JavaScript API
The JavaScript API is available for use on the Dev Zone and is included in the DDS
Web Services software distribution in the folder JavaScriptAPI. Documentation
and examples are available for download. This framework uses JSON derived objects
returned from DDS Web Services to provide modular fluid maps, panning, zooming,
geocoding, reverse geocoding, multi-point routing, numbered pins, customized pin
overlays, and street/hybrid/satellite views. You can get a map up and running on your
web page using only a few lines of JavaScript code.
2-26
The Developer Zone
October 15, 2010
2.4.7.1 Sample Code
The following sample code shows the HTML for a web page that includes a JavaScript
API map.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<html xmlns="http://www.w3.org/1999/xhtml">
<meta http-equiv="Content-Type" content="text/html; charset=UTF8">
<title>deCarta JavaScript API Example</title>
<script language="JavaScript" src="deCarta.js"></script>
<script language="JavaScript" src="CONFIG.js"></script>
<script language="JavaScript">
var map;
function init() {
var defaultPos = new Position("37.123 -121.234");
map = new Map(document.getElementById("map"));
map.authenticate(CONFIG.clientName,CONFIG.clientPassword);
/* Call these only once */
JSRequest.setDynamicScriptTagMode();
map.setShapeRendering("client");
map.centerOnPosition(defaultPos);
}
</script>
</head>
<body onload="init();">
<img src="img/logo.png">
<div id="map" style="width:800px; height:600px;></div>
<canvas id="canvas"></canvas>
</body>
</html>
2.4.8 The Mythical Town of Stickville
Stickville is a tiny, fictional town with a very simple set of map data, which is useful
for learning to use DDS Web Services features and for initial development and testing
of an application. The town has a simple grid of streets and avenues, with addresses
and other geographic data. It also has two points of interest (POIs).
2-27
October 15, 2010
The fictional town and its data have been adopted by the OpenLS community to use in
OpenLS compliance testing.
Here is a map of Stickville.
If you generate your own map of Stickville, you may notice that your map doesn’t
display the two POIs which are on this map. That is because some configurations on
the Dev Zone don’t display POIs. In fact, this map was created by using the “overlays”
feature of the Presentation Service (map drawing service).
Besides the grid of streets and the two POIs, Stickville has a set of political
subdivisions ranging from municipality to country.
For complete details about Stickville, please refer to the Stickville specification
Stickville-spec.doc.
2-28
CHAPTER 3
Deployment Options
When you are ready to deploy your application for commercial use, there are two
options for deployment:
• deCarta Hosted DDS Web Services.
With this option, deCarta provides the servers, software, and data for DDS Web
Services. For more detail, refer to “deCarta Hosted DDS Web Services” on page
3-2.
• Self-hosted DDS Web Services.
With this option, you provide the servers, you install DDS and DDS Web Services
software on the servers, and you make arrangements for data, either directly with
data vendors or through deCarta. For more information, refer to “Self-hosted DDS
Web Services” on page 3-5.
3-1
October 15, 2010
deCarta Hosted DDS Web Services
3.1 deCarta Hosted DDS Web
Services
With deCarta Hosted DDS Web Services, deCarta provides servers, software, and data
for DDS Web Services. deCarta takes care of capacity planning, load balancing,
maintaining servers, updating data, and so on. Your application sends web services
requests to Hosted DDS Web Services and receives responses. deCarta logs each
transaction and uses that log to generate periodic billing.
When you are ready to move your application from the non-commercial Developer
Zone to live, commercial use on Hosted DDS Web Services, you will do the following
steps:
• An application qualification procedure in conjunction with deCarta. You provide
information about your application, such as which web services you use and
expected traffic levels. This enables deCarta to plan capacity so that the needs of all
users can be met.
• deCarta provides you the URL to use to access Hosted DDS Web Services. You
simply change your application to use that URL instead of the Dev Zone URL.
• deCarta provides you your clientName and clientPassword to use in all
requests to Hosted DDS Web Services, as well as appropriate configuration
information to specify datasets and image styles. (These may be the same ones you
used on the Dev Zone.) You change your application, if necessary, to use those
values in your requests to Hosted DDS Web Services.
• You test and then go live!
3.1.1 Using JavaScript API with Hosted Web
Services
Running an application developed using the JavaScript API on Hosted Web Services
requires either a proxy server to pass XML requests from the customer’s domain to the
Hosted Web Services domain or a Dynamic Script Tag method referred to as JSON/
GET (JavaScript Object Notation). The XMLHTTPRequest method has a “same
origin policy”, a security measure for client-side scripting, in which a script loaded
from one origin cannot get or set properties of a document or script from a different
origin. In a Hosted Web Services environment, the HTML (from the customer’s site)
is from a URL different from the JavaScript.
For additional information on using a simple proxy server, see “Using a Simple Proxy
with JavaScript API” on page 3-3 and for information on the Dynamic Script Tags
method, see “Using Dynamic Script Tags (JSON/GET)” on page 3-4.
3-2
Deployment Options
October 15, 2010
3.1.1.1 Using a Simple Proxy with JavaScript API
SimpleProxy.class, located in com/deCarta/webservices/proxy is a simple
Java servlet that performs the proxy server functionality.
To activate SimpleProxy.class, add the following to the web.xml file:
<servlet>
<servlet-name>SimpleProxy</servlet-name>
<servlet-class>
com.deCarta.webservices.proxy.SimpleProxy</servlet-class>
<init-param>
<param-name>clientName</param-name>
<param-value>someclient</param-value>
<description>webservices user name</description>
</init-param>
<init-param>
<param-name>clientPassword</param-name>
<param-value>abc123</param-value>
<description>webservices password</description>
</init-param>
<init-param>
<param-name>webServicesURL</param-name>
<param-value>http://localhost:8080/openls/openls</
param-value>
<description>url of web services</description>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>SimpleProxy</servlet-name>
<url-pattern>/SimpleProxy</url-pattern>
</servlet-mapping>
To prevent clientName and clientPassword from being passed to and from the
AJAX client, use the proxy to inject the clientName and clientPassword into
XLS messages before the proxy forwards the XLS message to the OpenLS web
service. In order to do this, provide clientName and clientPassword init-params
in web.xml. If clientName and clientPassword attributes are present in the XLS
message received by the proxy, they will be overwritten.
3.1.1.2 AJAX Applications
For Ajax applications to use SimpleProxy, in CONFIG.js change the entry for the
OpenLS server to the location of the SimpleProxy server:
Credentials.url="http://localhost:8080/openls/
SimpleProxy";
3-3
October 15, 2010
deCarta Hosted DDS Web Services
This also hides the true location of the server from the end user if desired.
There are several free or open source proxies available for use in production
environments such as Apache 2.2.3, available as an open source download from
http://httpd.apache.org, can be installed and configured as a proxy server
using the proxy module.
A second open source, SquidNT, can also be used by downloading a zip file from
http://www.acmeconsulting.it/SquidNT. Configuration instructions are
available on the aforementioned web site.
3.1.1.3 Using Dynamic Script Tags (JSON/GET)
Rather than using a proxy server, instead you can configure Web Services and
JavaScript API to use Dynamic Script Tags (JSON/GET) to communicate with each
other.
To configure your environment to use the Dynamic Script Tags method refer to the
example titled “Getting Rid of Server of Origin (no more XMLHTTPRequest)” found
in the JavaScriptAPI/docs folder of the software distribution package.
3-4
Deployment Options
October 15, 2010
3.2 Self-hosted DDS Web Services
Since you run Self-hosted DDS Web Services on your own servers, the process is a bit
more complex than using deCarta Hosted DDS Web Services. Besides the obvious
steps of getting and setting up your servers and installing DDS and DDS Web
Services, there are some additional specific steps in configuring and operating web
services.
3.2.1 Setup and Configuration
Note: Please read any README.txt files and releasenotes.txt files for any late-
breaking or additional information that is not in this manual.
3.2.1.1 Installing the Software
Since DDS Web Services is part of the DDS software package, when you run the DDS
install process, you concurrently install the DDS Web Services software. No further
installation is necessary. The following sections will use the name install_dir to mean
the top-level directory of your DDS software installation.
3.2.1.2 Setting Up DDS
The DDS software comes with a default configuration file
install_dir\DrillDownServer\ddserver.cfg. The Drill Down Server Reference
Manual describes the configuration file in detail. Initially, you will probably be
concerned with only three aspects of the configuration file: license information,
datasets, and image settings.
3.2.1.2.1 License Key
You must edit the Username and LicenseKey entries in ddserver.cfg to use the
license information provided to you by deCarta. Otherwise, the DDS will not run.
3-5
October 15, 2010
Self-hosted DDS Web Services
3.2.1.2.2 Datasets
The default configuration file ddserver.cfg defines a dataset for the mythical town
of Stickville. For more information about Stickville, see “The Mythical Town of
Stickville” on page 2-27. Stickville provides a good simple case to get started and to
test your setup and configuration.
However, when you are ready to start using real-world data, you will have to define
one or more real-world datasets in ddserver.cfg that reference your licensed data.
The Drill Down Server Reference Manual explains all the details about setting up
datasets.
You will use your dataset information later in configuring DDS Web Services, as
described in “Setting Up DDS Web Services” on page 3-14. (To get started with
Stickville, you don’t have to do anything; it is already configured.)
3.2.1.2.3 Image Settings
The provided ddserver.cfg file defines a basic style for drawing maps. It also uses
ImageSettings parameters to reference several alternative styles of maps that you
can use, which are defined in other .cfg files, such as bright.cfg and oldworld.cfg. While you are getting started, it is easiest to use these provided
configurations.
When you are ready to create your own look and feel for your maps, you can modify
any of these provided configurations or create your own from scratch. You will have to
refer to the Drill Down Server Reference Manual and Drill Down Server and DDS
Web Services Quick Start Guide for information on the many options available to you.
Whether you use the provided ImageSettings configurations or create your own,
you will use those names later in configuring DDS Web Services, as described in
“Setting Up DDS Web Services” on page 3-14. (To get started with the provided
defaults, you may not have to do anything because they are already configured.)
Warning: In a self-hosted environment, ensure that any image settings configuration
file that you use is in the Drill Down Services folder. Some files, such as USCARTOGRAPHIC-NT.cfg, are not placed by default in the Drill Down Services folder.
Copy the desired image settings configuration file into the Drill Down Services folder
and restart DDS.
3.2.1.2.4 Projection Parameter
To use DDS 4.2.1 Web Services (and higher) and DDS 4.2.1 JavaScript API (and
higher), the Projection parameter of the DDS configuration file (ddserver.cfg)
and any image settings files must be set to MERCATOR_ELLIPSOIDAL.
3-6
Deployment Options
October 15, 2010
Warning: The 4.2.1 release (and higher) of DDS Web Services and of JavaScript
API are compatible with the DDS 4.1.3 sp03 Web Services release and the DDS 4.1.3
sp03 JavaScript API release, but are not compatible with versions prior to the 4.1.3
sp03 release.
3.2.1.3 Setting Up Your Web Server
A free Tomcat web server is included with the DDS Web Services package. DDS Web
Services also includes several startup scripts for starting various pieces of the software
that all work together. See “Starting DDS Web Services” on page 3-21 for information
about these scripts.
If you use a web server other than Tomcat, refer to the documentation for your server.
This manual cannot provide instructions for all other servers. Many references in this
and subsequent sections assume use of Tomcat, so you may have adjust references to
suit your own server.
DDS Web Services comes pre-configured to run a simple configuration of the Tomcat
web server (along with DDS Web Services and the HSQLDB database and a single
instance of DDS, all on the same host.
3.2.1.3.1 Connection to DDS
To run DDS on a different host machine than Tomcat, you must modify the file
install_dir\Web Services\server\Tomcat 5.0\webapps\openls\WEBINF\web.xml. The relevant lines of web.xml are the following:
<context-param>
<param-name>hostname</param-name>
<param-value>localhost</param-value>
<description>Drill Down Server hostname </description>
</context-param>
Change localhost to the correct IP address (or name) of the server where DDS will
run.
To run multiple instances of DDS to maximize image performance, you must modify
the cluster manager file install_dir\Web Services\ddscluster.xml
appropriately. This file defines a cluster of DDS instances (four image slaves), what
ports they run on, monitors them continuously, and restarts an instance of DDS if it
fails. It also saves you from having to create multiple DDS configuration files to avoid
port conflicts. An Ant task in the file install_dir\Web
Services\startServer.xml runs the cluster manager.
3-7
October 15, 2010
You need to modify the DDS configuration file ddserver.cfg. In the DDS
directory, copy ddserver.cfg to ddserver-master.cfg. Copy ddserver.cfg
to ddserver-imageSlave.cfg.
In ddserver-master.cfg make the following changes:
%MaxThreads=50
In the Plug-in section, for the I= line, add the port values identified in
ddscluster.xml:
I=127.0.0.1:20000,127.0.0.1:20004,127.0.0.1:20008,127.0.0.1:200
12
Save and close the file.
Next, modify ddserver-imageSlave.cfg
The Plug-in section must look like this:
A=
B=
C=
D=
E=
F=
G=
H=
I=DDSImg
J=
K=
L=
M=
N=
O=
P=
Q=
R=
S=
T=
U=
V=
W=
X=
Y=
Z=
Save and close the file.
3-8
Deployment Options
October 15, 2010
To start the cluster manager, copy the file install_dir\Web
Services\startServer.bat into a new file startCluster.bat. Add the
argument dds-clust to the end of the one line in the batch file such as the following:
startServer.xml dds-clust
Further details about this file are currently beyond the scope of this manual.
3.2.1.3.2 Configuring Image URL Path
You can configure your image URL path that gets returned from WS by modifying the
“image-servlet-path” context-param in the web.xml file.
In the following URL, the “/openls/image/” was modified to “/openls-stage/
image/”:
http://ws.decarta.com:8080/openls-stage/image/646834605.GIF
The attribute TDATA=true can now be used inside the image URLs for updating the
traffic information on a particular tile, if the server is enabled with traffic.
3.2.1.3.3 Configuring for Image Host Aliases in Portray Requests
When returnMaxImageHostAliases is set to TRUE in the web.xml file, the
deCarta GridLayer in a PortrayMapResponse has the attribute
maxImageHostAliases which is pulled up from the contex-param max-imagehost-aliases in the web.xml.
3.2.1.3.4 Connection to the Database
The information below provides details specific to Tomcat on how to configure the
databases. All Java web servers provide slightly different configuration mechanisms,
so consult your web server’s documentation. Regardless of the different configuration
mechanisms, all J2EE standard-compliant web servers will be able to deploy the
OpenLS web application.
If you will run your database on a different host machine than Tomcat or if you use a
different database program than HSQLDB, you will have to modify the file
install_dir\Web Services\server\Tomcat 5.0\conf\server.xml.
The file server.xml is the Tomcat configuration file, and it contains information
about the databases that are connected to Tomcat. The following are the relevant lines
of this file:
3-9
October 15, 2010
<parameter>
<name>username</name><value>sa</value>
</parameter>
<parameter>
<name>password</name><value></value>
</parameter>
<parameter>
<name>driverClassName</name>
<value>org.hsqldb.jdbcDriver</value>
</parameter>
<parameter>
<name>url</name>
<value>jdbc:hsqldb:hsql://localhost/olsdb</value>
</parameter>
As appropriate, change the references to username, password, HSQLDB, and
localhost.
If you use a database other than HSQLDB, there are additional required steps in
“Setting Up Your Database” on page 3-12.
3.2.1.3.5 Configuring Aerial/Satellite Imagery
DDS Web Services can return aerial imagery from GlobeXplorer by using the
TileGrid feature of the Presentation Service. To use this imagery, you must
configure the URL for GlobeXplorer imagery in the following section of the
install_dir\Web Services\server\Tomcat 5.0\webapps\openls\WEBINF\web.xml:
<context-param>
<param-name>globexplorer-url</param-name>
<param-value>http://GX_IMAGE_HOST>:PORT/tiles/
decarta?key=KEY</param-value>
<description>URL (including key) to globexplorer
imagery</description>
</context-param>
You must substitute the correct values for GX_IMAGE_HOST, PORT, and KEY. You
receive this information when you license the GlobeXplorer imagery.
3.2.1.3.6 In-Memory Caching
In-memory cache is configurable at certain zoom levels in the web.xml file. The four
parameters highlighted in the following examples are used to configure in-memory
cache.
<context-param>
3-10
Deployment Options
October 15, 2010
<param-name>tile-cache-size</param-name>
<param-value>100</param-value>
<description>FIXED_GRID_CACHE_PARAMETER: The cache size
in 'MEGABYTES', for fixed tile grid caching.Webservices
internal default is 15MB</description>
</context-param>
- <context-param>
<param-name>min-cache-zoom-level</param-name>
<description>FIXED_GRID_CACHE_PARAMETER: The Zoom level
between 1 and 21 (incl.),Webservices internal default is
8</description>
</context-param>
- <context-param>
<param-name>max-cache-zoom-level</param-name>
<description>FIXED_GRID_CACHE_PARAMETER: The Zoom level
between 1 and 21 (incl.), Webservices internal default is
17</description>
</context-param>
- <context-param>
<param-name>dds-req-extime</param-name>
<description>FIXED_GRID_CACHE_PARAMETER: The time in
'milliseconds' taken by DDS to execute a request, the
tiles that exceed this execution time will be cached along
with the higher zoom level tiles, Webservices internal
default is 70ms</description>
</context-param>
3.2.1.3.7 Disk Based Caching
DDS supports disk based caching for use with Image cache pre-renderer. The
parameters highlighted below are used to configure disk based caching.
<context-param>
<param-name>image-cache-servlet-path</param-name>
<param-value>/openls/image-cache/</param-value>
<description>can be used to overide image path
presented in the URL's generated for images.
For example replace ".../openls/image/
" with ".../openls/image-cache/"
</description>
</context-param>
<context-param>
<param-name>image-cache-dir</param-name>
<param-value>/imageCache</param-value>
<description>can be used to set the on-disk directory
into which the image-cache directory hierarchy is placed.
3-11
October 15, 2010
</description>
</context-param>
<context-param>
<param-name>cache-hostname</param-name>
<param-value>localhost</param-value>
<description>The hostname that will be used to fetch the
cached map images from disk.Commenting out this parameter will
default it to localhost </description>
</context-param>
<context-param>
<param-name>cache-image-port</param-name>
<description>the port that will be used in cache
image URLs generated by this web service. Commenting out
this parameter will result in ommission of the port from
the url, which implies port 80. </description>
</context-param>
<context-param>
<param-name>image-render-uri</param-name>
<param-value>http://localhost:8080/openls/image/
TILE</param-value>
<description>when an image is not found on the
disk cache, it will be retrieved from this 'live'
rendering uri. Typically the host is a loadbalancer.
</description>
</context-param>
For more information on the Image Cache pre-renderer, see “Starting the Image Cache
Pre-Renderer” on page 3-32.
3.2.1.3.8 Maximum Session IDs
The number of session IDs can be modified using the context-parameter maxsession-ids in web.xml.
3.2.1.4 Setting Up Your Database
DDS Web Services comes with the free HSQLDB database included.
The provided HSQLDB database already has the necessary tables set up for you. If
you use another database, you will have to create the necessary tables. Since database
table creation varies from database to database, you will have to use your database’s
documentation to determine how to create the required tables; the following are the
database table creation statements for HSQLDB:
CREATE SCHEMA PUBLIC AUTHORIZATION DBA
3-12
Deployment Options
October 15, 2010
CREATE MEMORY TABLE CACHE_PROPERTIES(ROUTE_CACHE_SIZE
INTEGER)
CREATE MEMORY TABLE USAGE(NUM_USES_GEOCODE
INTEGER,NUM_USES_REVERSE_GEOCODE
INTEGER,NUM_USES_DIRECTORY INTEGER,NUM_USES_ROUTE
INTEGER,NUM_USES_MAP INTEGER,NUM_USES_TILE
INTEGER,CLIENT_NAME VARCHAR(128))
CREATE MEMORY TABLE ROUTE(CREATION_TIME TIMESTAMP,HANDLE
VARCHAR(128),DDSRESPONSE VARCHAR)
CREATE UNIQUE INDEX HANDLE_INDEX ON ROUTE(HANDLE)
CREATE INDEX ROUTE_CREATION_TIME_INDEX ON
ROUTE(CREATION_TIME)
CREATE USER SA PASSWORD ""
GRANT DBA TO SA
SET WRITE_DELAY 60
SET SCHEMA PUBLIC
INSERT INTO CACHE_PROPERTIES VALUES(100)
3.2.1.4.1 Setting Up POI Database
The sample POI database provided in the DDS Web Services package has the required
tables set up for you. If you use another database, you will have to create the necessary
tables. Since the database table creation varies from database to database, you will
have to use your database’s documentation to determine how to create the required
tables: the following are the database table creation statements for the POI HSQLDB
database:
CREATE TEXT TABLE STICKVILLE_POI(SPATIAL_KEY
BIGINT,FREEFORM_ADDRESS VARCHAR,POINAME
VARCHAR,DESCRIPTION VARCHAR,PHONE VARCHAR,URL
VARCHAR,LATITUDE FLOAT,LONGITUDE FLOAT)
SET TABLE STICKVILLE_POI SOURCE "stickville_poi.txt;fs=|"
See “Connection to External Database” on page 4-19 for additional information.
3-13
October 15, 2010
3.2.1.5 Setting Up DDS Web Services
In the file install_dir\Web Services\server\Tomcat
5.0\webapps\openls\WEB-INF\classes\service-configuration.xml,
you create client definitions for all the clients that will be allowed to access your DDS
Web Services. The software distribution includes an initial
service-configuration.xml file with some initial clients defined. Each client
definition includes the following items:
• Client name, which is used in the clientName attribute of the request header of
every request sent by that client to DDS Web Services. See “clientName” on page
4-7 for more information about the clientName attribute and “RequestHeader”
on page 4-7 for more general information about request headers.
• Client password, which is used in the clientPassword attribute of the request
header of every request sent by that client to DDS Web Services. See
“clientPassword” on page 4-7 for more information about the clientPassword
attribute.
• The client’s role, which determines whether that client has authorized access to the
administrator’s tabs on the web console. The possible roles are admin and
ws-client. Only clients with role admin have access to the Usage Reporting,
Cache, and Admin tabs of the console.
• All the configurations that the client is authorized to use, including a default
configuration and alternate configurations. A configuration includes the following
parts:
A name for the configuration. A request header can have a configuration
attribute that uses this name to select this configuration for use in processing
the request. If the request has no configuration attribute, then it uses the
client’s default configuration.
A dataset. The dataset specifies the name of a dataset that is defined in the
DDS configuration file ddserver.cfg.
An image settings specification. This parameter specifies the name of an
ImageSettings entry in the DDS configuration file ddserver.cfg.
Now look at the supplied service-configuration.xml file to see the details
about this file. Here is the complete file as distributed in the software distribution; a
more thorough discussion of the parts of the file follows the file listing. The page size
of this manual requires line breaks where none actually exist in the file, but they are
fairly obvious; each case of dataset="stickville"/> on a line by itself is really a
continuation of the previous line:
<?xml version="1.0" encoding="UTF-8" ?>
- <client-configuration xmlns="http://telcontar.com/webservices/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://
telcontar.com/webservices/config file:/C:/project/webservices/schema/configuration/
WebServicesConfig.xsd">
- 
- <cloneable-client name="default-client" role="ws-client">
3-14
Deployment Options
October 15, 2010
<default-configuration dds-image-settings="DefaultImageSettings" ddsdataset="stickville" />
<configuration name="stickville" dds-image-settings="DefaultImageSettings" ddsdataset="stickville" />
<configuration name="blue-steel" dds-image-settings="blue-steel" ddsdataset="stickville" />
<configuration name="blue-steel-tile" dds-image-settings="blue-steel-tile" ddsdataset="stickville" />
<configuration name="old-english" dds-image-settings="marigold" ddsdataset="stickville" />
<configuration name="old-english-tile" dds-image-settings="marigold-tile" ddsdataset="stickville" />
<configuration name="bright" dds-image-settings="bright" dds-dataset="stickville" />
<configuration name="bright-tile" dds-image-settings="bright-tile" ddsdataset="stickville" />
<configuration name="old-world" dds-image-settings="old-world" ddsdataset="stickville" />
<configuration name="old-world-tile" dds-image-settings="old-world-tile" ddsdataset="stickville" />
</cloneable-client>
- 
- 
<client-clone password="abc123" name="someclient" cloneOf="default-client" />
- 
- <client name="admin" role="admin" password="12345">
<default-configuration dds-image-settings="DefaultImageSettings" ddsdataset="stickville" />
<configuration name="stickville" dds-image-settings="DefaultImageSettings" ddsdataset="stickville" />
</client>
- 
- 
- 
- <client name="us-carto-nt" password="us-carto-nt">
<default-configuration dds-image-settings="us-carto-nt" dds-dataset="navteq" />
<configuration name="us-carto-nt-online" dds-image-settings="us-carto-nt,http://
localhost:8080/openls/library?clientName=us-carto-nt&clientPassword=us-cartont&readFile=us-carto-nt.cfg" dds-dataset="navteq" use-dds-dataset-range="true" />
<configuration name="us-carto-nt" dds-image-settings="us-carto-nt" ddsdataset="navteq" use-dds-dataset-range="true" />
</client>
</client-configuration>
A Basic Client Definition
Look first at the section near the end of the file from <client name="admin" through
</client>, which defines a client element. This section defines a client whose
clientName is admin, whose clientPassword is 12345, and whose role is
admin. The admin role means that this client can access the administrator tabs of the
web-based console.
3-15
October 15, 2010
This client has only two possible configurations defined: a default one defaultconfiguration and one with the name stickville. The default configuration
uses the Stickville dataset and the default image configuration from the DDS
configuration file. In fact, all the client definitions in this initial file use only the
Stickville dataset. When you are ready to use your real-world licensed data, you will
have to create or modify clients with configurations that use appropriate datasets.
This sample file does not show it, but you can use additional client elements to
define additional clients with either role and with additional configuration
elements.
A “Cloneable” Client Definition
Now look at the large, earlier part of the file that begins <cloneable-client and ends
with </cloneable-client>. This parts defines a cloneable-client element,
which is like a prototype of a client definition. Its name is default-client, and you
can define clone clients of default-client that have all the same characteristics
except name and password. This makes it easier to create additional clients which all
have the same authorizations.
As you can see, this client has one default configuration (as all clients must) and a
multiplicity of additional authorized configurations.
You can use the Admin tab of the Web-based Console to create a new cloned client.
A “Clone” Client Created from a “Cloneable” Client
Look now at the single line that begins <client-clone. The client-clone element
means that this line defines a client which is a clone of another client. The attribute
cloneOf="default-client" means that this clone client is a clone of the cloneable
client default-client. It has all the characteristics of the cloneable client named
default-client (except name and password, of course), including role,
default-configuration, and additional authorized configurations.
Additional Notes on Clients
Your service-configuration.xml file can have as many client, cloneableclient, and client-clone elements as you want.
Each client or cloneable-client must have exactly one defaultconfiguration and can have as many additional configurations as you want.
Each client-clone has, by “inheritance,” exactly as many configurations as its
cloneOf client.
Note: The server loads the service-configuration.xml file every five minutes,
so you can add or delete clients or correct mistakes without restarting the server. If a
new version of the service-configuration.xml file contains an error, the server
sends an error message to the console and continues to use the previous “good” file.
However, if you use the Admin tab of the Web-based Console to create a new cloned
client, the change takes effect immediately, without waiting five minutes.
3-16
Deployment Options
October 15, 2010
Datasets
The use-dds-dataset-range="true" attribute should be used for a configuration in
which the dds-dataset-range attribute points to image settings which used the DDS
DatasetRange feature.
Character Encoding
The dds-char-encoding attribute should be used for any configuration in which the
DDS DataSet uses an encoding other than ISO-8859-1, which is the default value of
the dds-char-encoding attribute. The supported values for the dds-charencoding attribute are UTF-8, ISO-8859-1, ISO-8859-7. The character encoding is
passed along in the DDS CharacterEncoding keyword, and is used in the
marshalling and unmarshalling of the bytes over the socket to DDS.
DDS Web Services performs all communications with the JavaScript API via UTF-8
encoding. The JavaScript API communicates to Web Services exclusively using UTF8 encoding, and never communicates directly to DDS.
3.2.1.6 Supporting Wildcard Names
If a clientName is created ending in “:”, any clientName beginning with the
wildcard name will authenticate against the clientPassword of the wildcard
clientName. For example, given clientName “someclient:” with
clientPassword “123”, the server will authorize “someClient:1” and
“someClient:2” against the password “123”. Login and usage tallies will be
collected separately for someClient1: and someClient2:.
3.2.2 Enabling DDS Web Services Fleet Services
This section describes the procedure to deploy fleet services (an extension of DDS
Web Services) in DDS Web Services 4.5.2.
Before enabling the fleet services, be sure you have deployed DDS and Web Services.
1. Unzip the fleet extension file fleet.zip located in [4.5.2WS]\ext\fleet.
The following five folders should be displayed:
• doc, which includes all fleet-related documents
• lib, which includes the fleet extension jar file decarta-fleet-4.5.2.jar
• src, which includes sample Java files to demonstrate how fleet features work
• test_xml, which includes XML files to be executed in the Web Service console
2. Copy decarta-fleet-4.5.2.jar, the fleet extension jar file into
3-17
October 15, 2010
[4.5.2WS]\server\Tomcat 6.0.18\webapps\openls\WEB-INF\lib.
Note that [4.5.2WS] indicates the directory in which the Web Services 4.5.2 is
deployed.
3. Open [4.5.2WS]\server\Tomcat 6.0.18\webapps\openls\WEBINF\web.xml.
4. Locate the following fleet configuration section in the web.xml file and
uncomment the fleet configuration section. Save the web.xml file.
<resource-ref>
<description>Fleet DB Connection</description>
<res-ref-name>jdbc/fleet</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
5. Open [4.5.2WS]\server\Tomcat 6.0.18\webapps\openls\WEBINF\classes\service-binding.xml.
6. Locate the following fleet configuration section in the service-binding.xml
file and uncomment the fleet configuration section. Save the servicebinding.xml file.
<openls-service className="com.decarta.fleet.server.BasicExclusionZoneService"
requestName="ExclusionZoneRequest"/>
<openls-service className="com.decarta.fleet.server.BasicGeofencingService"
requestName="GeofencingRequest"/>
<openls-service className="com.decarta.fleet.server.BasicDispatchService"
requestName="DispatchRequest"/>
<openls-service
className="com.decarta.fleet.server.BasicRouteComplianceService"
requestName="RouteComplianceRequest"/>
7. Open [4.5.2WS]\server\Tomcat 6.0.18\conf\server.xml.
8. Locate the following fleet configuration section in theserver.xml file and
uncomment the fleet configuration section. Save the server.xml file.
<Resource name="jdbc/fleet"
auth="Container"
type="javax.sql.DataSource"
factory="org.apache.commons.dbcp.BasicDataSourceFactory"
maxActive="10"
maxIdle="5" maxWait="10000" username="sa" password=""
driverClassName="org.hsqldb.jdbcDriver"
url="jdbc:hsqldb:hsql://localhost/olsdb"/>
9. Launch HSQLDB at [4.5.2WS]\server\hsqldb.
10.Launch Tomcat Server with fleet extension.
3-18
Deployment Options
October 15, 2010
3.2.2.1 Verifying Fleet Services Install
3.2.2.1.1 Database Diagnostic
1. Launch the database manager using
[4.5.2WS]\server\hsqldb\runDBManagerSwing.bat.
2. Configure the connection string as shown in the following Connect window:
3. Click OK to connect the database. The fleet tables listed below should be
displayed.
4. Enter the SQL statement in the text area and click Execute SQL.
3-19
October 15, 2010
3.2.2.1.2 Service Diagnostic
1. Open the web service console at http://servername:8080/openls/
console.
2. Run the XML files for Geofence Service, Dispatch Service, and Route Compliance
Service located in [4.5.2WS]Web Services\test_xml.
3. Check the changes made by the service call in the database.
3.2.3 Setting up Apache Tomcat as a Windows
Service
3.2.3.1 Before Getting Started
Before getting started, make sure there is no web server running on port 80 on your
machine. Click Start->Administrative Tools->Services. If a service is
listed, select it and then click Stop.
To prevent a service from starting on your machine after a reboot, go to Properties.
Set Startup Type to Manual instead of Automatic.
3.2.3.2 Installing Tomcat as a Service
1. Download and install the Java SE JDK 6, or whichever JDK version you are using,
from sun.com at http://java.sun.com/javase/downloads/index.jsp.
Accept the defaults of the installation.
2. Set an environment variable JAVA_HOME to the installation of your JDK such as
C:\Program Files\Java\jdk1.6.0_11.
3. Edit the service.bat file found in the path {DDS_INSTALL}\Web
Services\server\Tomcat 6.0.18\bin\....
Add the following to ensure a CLASSPATH is set appropriately:
....
set EXECUTABLE=%CATALINA_HOME%\bin\tomcat6.exe
rem explicitly set CLASSPATH
set CLASSPATH=%JAVA_HOME%\lib\tools.jar
....
4. Start service.bat from a command prompt from the Tomcat 6.0.18 directory,
type:
> bin\service.bat install
5. Start the windows services manager (services.msc). Find the service “Apache
Tomcat”. Click Start.
3-20
Deployment Options
October 15, 2010
6. Verify by directing your browser to http://localhost:8080/openls/
console.
3.2.3.3 Removing Tomcat as a Service
From the command prompt from the Tomcat 6.0.18 directory, type:
> tomcat6 //DS//Tomcat6
If the service is running, it will stop and be deleted.
Note: If you want to set up Apache Tomcat as a Windows Service, be sure to refer to
Tomcat’s own documentation.
3.2.4 Operation
3.2.4.1 Starting DDS Web Services
The batch file install_dir\Web Services\startServer.bat for Windows
platforms or install_dir\Web Services\startServer.sh for Linux/UNIX
platforms starts all the software needed to use DDS Web Services: the Tomcat web
server, DDS Web Services, the HSQLDB database, and a DDS. When you run this
file, it initially displays a “splash screen,” as shown here:
It may take a few seconds for the splash screen to appear. Then a window appears with
two sections that display the standard output of the web server and of the DDS.
3-21
October 15, 2010
The desktop development GUI should never be used in a production environment. In a
production environment, the OpenLS web application should be deployed onto the
web server of your choice. You may also choose to use your own database, and a
customized configuration of a DDS cluster. The setup of these pieces depends heavily
on the operating system and operational environment.
Note: A progress bar at the bottom of the browser progresses from left to right. If
your DDS is configured with large datasets, it may take several minutes for DDS to
start and for the progress bar to complete.
3.2.4.2 Logging Features
3.2.4.2.1 Transaction and User Accounting
Web Services logs transactions and user accounting information through the
log4j.properties file found in install_dir\Web Services\server\Tomcat
5.0\webapps\openls\WEB-INF\classes. Logging can capture contextual
information such as “msg=maneuver-map” to provide contextually relevant
information, which in turn supports a variety of billing and accounting models.
• User ID (UID). Logging can generate a UID, an identifier generated for each toplevel web service request. Nested requests, such as geocodes within a route request,
inherit the UID of the parent request and are logged separately. UIDs are
guaranteed to be unique, even across server reboots.
• Request ID (RID). Logging supports RID, the Request ID provided by the client.
• Session ID (SID). Logging supports SID, the Session ID provided by the client.
You can edit log4j.properties to turn logging features on and off.
Turning on the logging feature for DDSQL shows the DDS queries that Web Services
generates and the responses DDS returns. This is useful for troubleshooting. In the
log4j.properties file, to turn logging DDSQL on, change the value of the DDS
REQUEST and DDS RESPONSE from FATAL to INFO as shown in the following
example:
#Enable the DDS_REQUEST and DDS_RESPONSE at INFO level to
see DDSQL
log4j.category.DDS_REQUEST=INFO, CONSOLE
log4j.category.DDS_RESPONSE=INFO, CONSOLE
Warning: Enabling certain forms of logging can degrade performance significantly
and should not be used in production environments.
3-22
Deployment Options
October 15, 2010
3.2.4.2.2 Maneuver Generation Debugging
Turning on the logging feature for routing shows the IDs of each routing maneuver
that generates text. This is useful for debugging your maneuver rules files. In the
log4j.properties file, to turn on the logging feature for routing, change the value
of the ROUTE_DEBUGGER from FATAL to INFO as shown in the following example:
#Enable debugging of XML route instruction generation
rules
log4j.category.ROUTE_DEBUGGER=INFO, TERSE_CONSOLE
Here is an example of routing debugger output:
{ROADUSE=3, SN=1st St, DIST=R0.1946, TIME=15.57 sec,
VR=4,4100382,-7200300,-82,0,-100,0,-100,0, OHED=South,
OANG=180.0, LL=41.00100,-72.00300, TANG=-90.0, DANG=90.0,
DSTR=3rd Ave}
Generated Instruction: Begin on 1st St heading South towards 3rd Ave.
<maneuver id='turn'>
Generated Instruction: Turn onto 3rd Ave.
Each output group from RMAN is shown between a set of curly braces. If a maneuver
element from the maneuver rules file is executed, the maneuver element is printed to
the screen (this is shown in bold above). As you can see, the first output group leads
the generation of the departure maneuver, AND the first turn.
3.2.5 Editing Image Settings
For Self-hosted DDS Web Services users only, the patent-pending Online Image
Settings Editor edits image settings files located in an online image settings library or
repository and allows the user to see immediately the impact of changes to the image
settings file without having to run DDS locally.
The Online Image Settings Editor or “Image Settings Editor” has a “Smart Edit”
feature which provides users with a variety of windows-based tools including a color
palette, list boxes for font options, line styles, and area styles. See “Smart Edit
Features” on page 3-29.
For complete information on syntax used in image settings, refer to the Drill Down
Server Reference Manual. Additional information on map displays is available in the
DDS and DDS Web Services Quick Start Guide.
Warning: The Image Settings Editor is available only in the Self-hosted DDS Web
Services environment and should not be used in a production environment.
3-23
October 15, 2010
3.2.5.1 Browser Compatibility
The Image Settings Editor is compatible with the following browsers:
• Internet Explorer 6.0
• Mozilla Firefox 2.0.0.3
The Editor supports screen resolutions above 1024 X 768. It is best viewed at 1400 X
1050 pixels screen resolution.
3.2.5.2 Configuration for Online Image Settings Editor
3.2.5.2.1 Create Client Folder
Create a folder whose name matches your Web Services clientName. The folder
must reside in webapps/openls/WEB-INF/library. The image settings are
placed, read, and written in this online library.
3.2.5.2.2 LibraryServlet
Verify that the LibraryServlet.class is in webapps/openls/WEB-INF/
classes/com/telcontar/openls/server/library and verify that the
web.xml refers to the LibraryServlet.
3.2.5.2.3 Modify service-configuration.xml With Editable Filename
In the webapps/openls/WEB-INF/library, create a configuration element in
service-configuration.xml which is aware of your image settings file entry in
the library. The following example uses stickville, a sample image settings file
distributed with Web Services and is the Image Settings Editor’s default image
settings file.
<configuration name="stickville" dds-image-settings="stickville,http://
localhost:8080/openls/library?clientName=map-sampleapp&clientPassword=letmein&readFile=stickville" ddsdataset="stickville" use-dds-dataset-range="true"/>
Note: In order for image settings to change on-the-fly, the DatasetRangeN attribute
must be defined in the image settings file. For example, in the image settings file
stickville, DatasetRange1=stickville, k0-k5000.
3-24
Deployment Options
October 15, 2010
Warning: Note that in the XML, ampersands must be escaped using “&” in
order for the XML document to validate. If you are a Self-hosted customer and have
difficulty accessing online map image settings, you can turn on some useful
debugging output by enabling the LIBRARY_LOG in log4j.properties. For more
information on log4j.properties, refer to “Logging Features” on page 3-22.
3.2.5.3 Online Library of Image Settings
The Image Settings Editor can be used to edit existing image settings files which are
then stored in an online library which matches your Web Services clientName. In a
Self-hosted DDS Web Services environment, image settings can be edited in real-time
and used in conjunction with the DDS functionality of reading image settings from a
URL.
An image settings file can be added to the library one of two ways:
1. Add a file to the folder whose name matches your Web Services clientName. The
folder must reside in webapps/openls/WEB-INF/library. If the library folder
does not exist, create it.
2. Open an HTTP connection to http://servername.com:8080/openls/
library?clientName=<CLIENTNAME>t&clientPassword=<PASSWORD>&w
riteFile=mySettings.cfg and post your file’s content to the library. Note that
you must replace CLIENTNAME and PASSWORD with a valid clientName and
clientPassword. Replace mySettings.cfg with an image settings file name
of your choice.
After an image settings file has been added to the library, it can be retrieved from the
library via HTTP. You can point your browser at the following URL to see the file’s
content. Note that “writeFile” is NOT present in the URL, whereas “readFile” is.
http://servername.com:8080/openls/
library?clientName=someclient&clientPassword=abc123&readFile=mySetting
s.cfg
You can also retrieve the image settings file by selecting it in the Image Setting box in
the Image Settings Editor window.
Once your image settings file are added to the library, DDS Web Services can use your
online image settings to render maps through DDS, and you can change your file’s
content in real time. You must create a configuration element in serviceconfiguration.xml which is aware of your entry in the library as described in
“Modify service-configuration.xml With Editable Filename” on page 3-24.
3.2.5.4 Starting the Image Settings Editor
Before starting the Image Settings Editor, DDS and DDS Web Services must be
running.
3-25
October 15, 2010
3.2.5.4.1 Accessing the Image Settings Editor
You can access the Image Settings Editor at start.html in the Web Services/
JavaScriptAPI/ImageSettingsEditor folder. You should use a recommended
browser such as one listed in “Browser Compatibility” on page 3-24.
Warning: Do not make any changes in the Web Services/JavaScriptAPI/
ImageSettingsEditor/img folder. Doing so may break the Image Settings Editor.
When you access the Image Settings Editor, you will see a login window similar to
this one:
Figure 3.1. Image Settings Editor Login Window
Enter your client name and password. Click Login.
Figure 3.2. Default Image Settings Editor Display Window
The newly displayed window includes the following:
• Configuration box, which includes a drop down list of configuration files included
in the default service-configuration.xml file
• Image Settings box, which includes a drop down list of image settings files
• Latitude and Longitude, which currently default to coordinates in Stickville.
3-26
Deployment Options
October 15, 2010
After a successful login, the Client Name, Client Password, and Host buttons are
inactivated.
3.2.5.4.2 Edit Window
Click Start. The Image Settings Editor edit window displays an image of Stickville
such as in Figure 3.3.
Figure 3.3. Edit Window of Image Settings Editor.
The Edit window is composed of the following four parts:
1. Credentials, which lists the client name, password, host name, image settings file
and configuration file, and latitude and longitude
2. Edit Box, or text display of the actual image settings file
3. Controls, or buttons, which include Smart Edit, Simple Edit, Save, Preview, and
Batch ReNumbering.
4. Map, which displays the map that the image settings file renders
The Edit Box uses three modes of editing:
1. Basic Edit, which is loaded on startup by default. Users simply use the Edit Box as
a text editor and modify the image settings manually.
3-27
October 15, 2010
2. Simple Edit, which is invoked when Simple Edit is selected. It refreshes the edit
box with supported features; users can make changes to many features at the same
time; for example, changing the color and font for all arterial roads.
3. Smart Edit, which is invoked when Smart Edit is selected, refreshes the Edit Box
with editable portions of the image settings file either highlighted in a different
font, or otherwise visually different from the uneditable portions of the file. Colors,
fonts, line styles, and area styles are editable.
For more information on Smart Edit, see “Smart Edit Features” on page 3-29.
When Save is selected, a pop-up window displays a text box in which you select from
a list or enter the new image settings file. Incidentally, when Save is selected, the Save
button changes to Save As. To close the pop-up window without saving changes,
select X. To save your changes, select Save As. The following happens:
• The pop-up window close
• the Map portion of the window is refreshed and the map reflects modifications to
the image settings file made in the Edit Box
• The Save As button reverts back to Save.
• The Image Settings drop-down list is updated.
Figure 3.4 shows the Simple Edit window.
Figure 3.4. The Simple Edit Window.
3-28
Deployment Options
October 15, 2010
3.2.5.4.3 Smart Edit Features
When Smart Edit is invoked, several tools are available for editing the image settings
file. In the Edit Box portion of the window, position your cursor on any font setting. A
view similar to Figure 3.5 is displayed.
Figure 3.5. Smart Edit Features.
In the upper right portion of the window, a color palette and two buttons Select and
Close are displayed.
The Smart Edit tools have a color palette common to all.
The Color Palette
Any RGB value in the Edit Box that is underlined with color dashes when selected
brings up the Color Palette.
The user can move the cursor on the palette to change the colors. The RGB and the
HEX values adjust to the cursor location on the palette.
Once the desired color is chosen, select Select to copy the selected RGB values into
the line of the image settings file found in the Edit Box.
3-29
October 15, 2010
The Font Box, PointStyle Box, LineStyle Box, AreaStyle Box
In the Edit Box and when in Smart Edit mode, selecting any FontN= or
LineStyleN= or AreaStyleN= lines that are underlined with red dots invokes the
Font Box, PointStyle Box, LineStyle Box, or AreaStyle Box respectively. Those boxes
appear as follows:
The options available in each of the boxes provide a Windows-interface to the options
available via the DDS. All the values in the drop down lists are pre-populated. Only
valid values are present. All the optional entities are marked by “(Opt.)” on the side.
For complete details of the image settings options, refer to the Drill Down Server
Reference Manual.
You can add or delete point, line, and area styles by clicking the Add / Delete
Styles button. When you do so, the editor automatically re-numbers the styles as
needed.
3-30
Deployment Options
October 15, 2010
The Preview button enables you to preview a map with your new settings before
saving the settings file.
Using Multiple Views
In Smart Edit, you can display multiple map views to see the effects of your changes
in multiple areas. Click the Add New View (Max 4) button to add a new view based
on freeform address, latitude-longitude, and zoom level. You can have up to four
views at a time. After adding new views, the window looks similar to Figure 3.6.
Figure 3.6. Multiple Map Views.
3.2.6 Image Cache Pre-Renderer
For Self-hosted DDS Web Services users only, the Image Cache Pre-renderer tool
enables you to create a cache of all the images at all zoom levels (or selected subsets)
in advance. Having such a cache available can significantly improve system
performance.
Warning: The Image Cache Pre-Renderer is available only in the Self-hosted DDS
Web Services environment and should not be used in a production environment.
3-31
October 15, 2010
3.2.6.1 Compatibility
The Image Cache Pre-Renderer is compatible with the following browsers:
•
•
•
•
Internet Explorer 7.0.5730.13
Mozilla Firefox 3.0.4
Safari 3.1
Google Chrome 0.4.154.25
The pre-render works only with the 4.3.4 or later releases of DDS and DDS Web
Services. Be sure also to use the latest version of deCarta.js.
3.2.6.2 Setup and Configuration
To use the pre-renderer, make the following changes in your web.xml file:
• Disable in-memory cache by commenting out the following context-param
entries: tile-cache-size, min-cache-zoom-level,
max-cache-zoom-level, and dds-req-extime
• Enable the disk based cache by un-commenting the following context-param
entries: image-cache-servlet-path, image-cache-dir,
cache-hostname, cache-image-port, and image-render-uri.
• Set the image-cache-dir to the path where you want to create the cache. The
default directory is /imageCache. This directory is created at C:\imageCache in
Windows and /imageCache in Linux.
• You can set the maximum number of image rendering threads that are used by the
deployer of the pre-renderer service by modifying the context-param entry
renderer-pool-max-active. This defaults to 8 when renderer-pool-maxactive is not used. The maximum permitted is 16.
The pre-renderer stores images in folders based on image setting names. For example,
the cache created for the configuration bluesteeltile is in folder
…imageCache\bluesteeltile.
Note: You can clear the entire cache simply by deleting the imageCache folder. You
can also clear the cache corresponding to one configuration by deleting that
configuration’s sub-folder within imageCache.
3.2.6.3 Starting the Image Cache Pre-Renderer
Before running the pre-renderer, be sure to have service-configuration.xml set up and
web.xml configured as described in “Setup and Configuration” on page 3-32.
Start the DDS and Web Services before trying to run the pre-renderer.
3-32
Deployment Options
October 15, 2010
To start the pre-renderer, open index.html in your browser. index.html is located
in the ImageCachePre-Renderer subdirectory of JavaScriptAPI.
The following screen appears:
3-33
October 15, 2010
Enter your client name and password, and click Login. The initial screen appears
with the default map of Stickville, if you use the default configuration. This example
uses the blue-steel-tile configuration:
3-34
Deployment Options
October 15, 2010
3.2.6.4 Using the Image Cache Pre-Renderer
At the default screen, you can select the location in the “Move to another location”
box and set the pre-render parameters in the “Pre-Render Parameters” area:
3-35
October 15, 2010
Click the Start Rendering button, and the rendering begins. The display shows a
running status:
3-36
Deployment Options
October 15, 2010
You can pause or resume the rendering by clicking the pause/resume button in the task
list in the Status area. You can also stop all the tasks by clicking the Stop All
button.
After the pre-rendering is complete, DDS Web Services uses the pre-rendered cache
automatically because of the configurations settings that you created.
3.2.7 Troubleshooting
3.2.7.1 Images
The browser retrieves image tiles based on their URLs. If you see “broken image”
links on your draggable map, it may be because your browser cannot resolve the
hostname of the image’s URL. When Web Services generates the URL for the image,
Web Services looks up the hostname of the server where Web Services is running, and
uses that hostname in the URL for images it generates. If the Web Services hostname
is not properly configured in DNS, it may be necessary to manually specify the
hostname that Web Services generates for image URLs. You can do this by setting the
image-host and image-port context parameters in the web.xml file for the
OpenLS web application.
3-37
October 15, 2010
3-38
CHAPTER 4
OpenLS Core Services
and deCarta Extensions
This chapter explains and illustrates the XML formats for queries and responses used
in DDS Web Services.
Note: You don’t have to be an XML expert to learn to use the XML in DDS Web
Services. With only a small amount of explanation and looking at the examples, you
will quickly be able to write your own queries and interpret the responses to them. If
you already are an XML expert, you may find it easier and faster to examine the
schemas and the examples than to read all the details in this chapter.
4-1
October 15, 2010
XML Schemas
4.1 XML Schemas
The schemas which define the format of valid requests and responses are in the
directory install_dir\docs\xml-schema\. There are four general categories of
schemas:
• the highest level general XLS schema, XLS.xsd, which defines the general format
of requests and responses.
• one schema for each of the core services of OpenLS. For example,
DirectoryService.xsd is the schema for the directory service.
• auxiliary schemas that generally define data types which are used in other schemas.
• deCarta XML schemas that are specific to deCarta.
The following table lists all the schemas with a short explanation of their contents:
Table 4.1. List of XML Schemas
Schema File
Purpose—Formats of Requests and
Responses for …
General format of XLS requests and responses
XLS.XSD
The highest level schema, on which all others
are based.
Core services schemas
4-2
DirectoryService.xsd
Lookup points of interest (POIs) including POIs
in an external database in RDBMS format.
DispatchService.xsd
Locates best vehicles for jobs, or best jobs for
vehicles by calculating each vehicle distance
and estimated time of arrival (ETA) to job and
returning to the client the best suited vehicle (or
best jobs for vehicles).
GeofencingService.xsd
Defines geofences, areas around a particular
place, point, etc., and then assigns a variety of
properties to geofences.
LocationUtilityService.
xsd
Geocoding and reverse geocoding.
PresentationService.xsd
Draw maps and overlay shapes on a map
display.
RouteComplianceService.
xsd
Calculate a route using route styles, vehicle
(truck, commercial, vehicle), with or without
traffic and monitor a route for compliance.
RouteService.xsd
Calculate routes.
October 15, 2010
Table 4.1. List of XML Schemas
Schema File
Purpose—Formats of Requests and
Responses for …
Auxiliary schemas
ADT.XSD
Abstract data types, such as positional
information, POI information, addresses, etc.
FleetBase.xsd
Common types used by fleet related services.
geometry.xsd
Geometric objects.
gml4xls.xsd
“Geographic markup language” for XLS.
UOM.XSD
Units of measure.
deCarta XML schemas
ExclusionZoneService.xsd
Defines exclusion zones, including areas around
a particular place, road segments, etc., and then
assigns a variety of zone properties and
restricted active times to those defined zones.
GeocoderStateMachine.xsd
Controls the content of the geocode XML file.
POISchema.xsd
Mapping OpenLS PointofInterestType to
external POI database.
RouteInstructions.xsd
RMAN XML rules.
RUOKService.xsd
Test if the service is up and running (a deCarta
extension).
ScrollingService.xsd
Supports scrolling of street names.
TrafficService.xsd
Traffic information (not yet implemented. A
deCarta extension).
4-3
October 15, 2010
Requests and Responses
4.2 Requests and Responses
This section describes some of the important elements and attributes of requests and
responses in general. Subsequent sections describe more specific elements and
attributes of the various core services’ requests and responses.
Your application/client sends requests to DDS Web Services and DDS Web Services
sends responses to your application/client.
Note: The XML schemas are the complete and definitive documentation for request
and response formats. This section provides a brief description of many parts of the
requests and responses, to help users learn to understand them, but it is not a complete
reference.
Note: A tip for using this manual in PDF form: Many of the names of XML elements
and attributes in this section are similar, and they have important structured,
hierarchical relationships to each other. It may help to turn on PDF bookmarks while
reading this section because the bookmarks generally reflect the same hierarchical
structure.
4.2.1 High Level View of Requests and
Responses
All DDS Web Services requests and responses follow a similar high-level
organization. The following example illustrates this organization. It uses the sample
request Directory01.xml and the response from the Dev Zone’s Web-Based
console to that request to illustrate the organization. Colored rectangles show parallel
4-4
October 15, 2010
elements of request and response. Colored ovals show the extent of high level
elements.
Figure 4.1. Request and Response—Highest Level Elements.
<ns1:XLS ns1:lang="en" version="1" xmlns:ns1="http://www.opengis.net/xls">
<ns1:XLS ns1:lang="en" version="1.0" xmlns:ns1="http://www.opengis.net/
xls">
<ns1:RequestHeader sessionID="999" clientName="xxxxxx"
clientPassword="xxxxx"/>
<ns1:POILocation>
<ns1:Nearest>
<ns1:StreetAddress>
</ns1:Address>
</ns1:Nearest>
</ns1:POILocation>
<ns1:POIProperties>
</ns1:Request>
</ns1:XLS>
<ns1:ResponseHeader sessionID="999"/>
<ns1:POIContext>
<ns2:pos>41.002 -72.0005</ns2:pos>
</ns2:Point>
<ns1:StreetAddress>
ns1:Place>
</ns1:Address>
</ns1:POI>
value="0.082190543709009009076815743810584535822272300720214843
75"/>
</ns1:POIContext>
</ns1:Response>
</ns1:XLS>
4-5
October 15, 2010
As the example shows, requests and the responses to them have highly parallel
formats. Here is the hierarchical view of the XML formats:
xml version—the version of XLS used—same for request and response
XLS—the XLS content—same for request and response
RequestHeader or ResponseHeader—basic header information. The
request requires an ID and password for validation that the request is from a
legitimate client.
Request or Response—the “meat” of the request or response.
Details of the request or response. These vary greatly, depending on
the type of request.
4.2.2 General XML Elements
The elements in this section are common to both requests and responses.
4.2.2.1 xml version and XLS
The xml version and XLS elements form the outermost “wrapper” of every request.
In most cases, you will simply copy the same information into this part of every
request.
One exception is that you may use a different value for the lang attribute, which
specifies a working language, using an ISO 3116-1 2-letter language code. However,
currently DDS Web Services does not process or use the lang code.
The following example is from the XML sample code in Directory01.xml:
<ns1:XLS ns1:lang="en" version="1" xmlns:ns1="http://www.opengis.net/
xls">
...
</ns1:XLS>
4-6
October 15, 2010
4.2.3 Requests
4.2.3.1 RequestHeader
The request header requestHeader provides some basic identification and
validation information to DDS Web Services. Attributes of the header include a user
ID (clientName), password (clientPassword), and session identifier
(sessionID), and sometimes can include a gzip compression request.
<ns1:RequestHeader clientPassword="xxxxx" sessionID="999" AcceptEncoding: gzip clientName="yyyyy"/>
4.2.3.1.1 clientName
clientName is an attribute of the request header that identifies a user. When sending
requests to the Dev Zone, you must use the clientName which you received when
you signed up for the Dev Zone. When you use the web-based console on the Dev
Zone, you must login; as long as you stay logged in, the web-based console
automatically fills in your clientName and clientPassword in requests. In Hosted
DDS Web Services, you use the clientName and clientPassword assigned by
deCarta. If you are using Self-hosted DDS Web Services, you will set up the valid
names and passwords in the service-configuration.xml file, as described in
“Setting Up DDS Web Services” on page 3-14.
clientName="xxxxxx"
If a clientName is created that ends with a ‘:’ character, then the clientName field
of the request header may include any additional characters after the colon. For
example, if the clientName is someClient: then the server will accept requests
from someClient:abc if the correct password for someClient: is given. The
server collects login and usage tallies separately for each variation.
4.2.3.1.2 clientPassword
clientPassword is also an attribute of the request header. Obviously, it must match
the stored password for the user specified by clientName.
4-7
October 15, 2010
clientPassword="yyyyy"
4.2.3.1.3 sessionID
A sessionID must be used by applications that use deCarta's proprietary TileGrid
functionality. The sessionID insures that session-specific information, such as a
user's route or overlays, is consistently rendered onto map tiles observed by the user of
a particular session. It is good practice for all applications to supply a sessionID that
is unique to each end-user of their application. For example, you could combine the
user name with a date-time stamp to create a sessionID. Please refer to the white
paper on AJAX tiling applications for more information on that subject.
Persistent Sessions
The StatefulServlet.java invokes persistent storage of information, in which
various information can be stored and persist server-side between session access and
beyond the reboot of the server. The example file StatefulClient01.java
provides a sample. When in the request header the sessionID= "-" the hyphen tells
the server to produce a new sessionID and that session ID would be used to navigate
between the pages upon subsequent requests. By default the first response would
contain the first page with the session ID. Additional requests using this session ID
would result in the results getting persisted in the session and be paginated. Also,
hasNextPage="true" indicates that there are more records in the page to be
browsed.
4.2.3.1.4 configuration (deCarta extension)
The attribute configuration is a deCarta extension to the OpenLS specification of
RequestHeader. The value is a named configuration which specifies datasets and the
appearance of maps.
The following example is copied from the Client Web App sample program:
configuration="old-english"
You can see other examples by using the Client Web App at
http://ws.decarta.com:8080/clientwebapp. Get a map, then click to view
the request XML and find the configuration attribute, then select a different
configuration from the configuration drop-down list, and find the new
configuration attribute.
4-8
October 15, 2010
4.2.3.2 Request
The Request element is the main part of a request. It contains all the information that
identifies the type of request and all the specific details of the request. It is everything
besides the header of the request.
The following example is from the XML sample code in Geocode01.xml:
<ns1:Request requestID="11" methodName="GeocodeRequest"
maximumResponses="25" version="1.0">
<ns1:GeocodeRequest>
<ns1:StreetAddress>
<ns1:Street>First Ave.</ns1:Street>
</ns1:Address>
</ns1:GeocodeRequest>
</ns1:Request>
As the example shows, the Request element has several attributes and contains a
number of additional elements. The next few sections describe these attributes; the
additional elements depend on the request type’s core service (methodName), so
additional elements are explained in the sections for the core services.
4.2.3.2.1 methodName
The methodName attribute of Request specifies which kind of request this is; that is,
it says which core service is to be used. The possible values are the following, which
have the obvious meanings:
•
•
•
•
•
•
•
•
•
•
DirectoryRequest
DispatchRequest
GeocodeRequest
GeofencingRequest
ReverseGeocodeRequest
PortrayMapRequest
DetermineRouteRequest
RouteComplianceRequest
ScrollRequest
TrafficRequest (future)
methodName="DirectoryRequest"
4-9
October 15, 2010
4.2.3.2.2 requestID
The value of the requestID attribute can be any string that you want. Typically you
use it to correlate responses with the requests that you sent.
requestID="10"
For route compliance requests, requestID automatically assigns an integer to the
route compliance. The unique route ID is saved to a database and is used to correlate
future route compliance service requests to the route compliance. For additional
information on Route Compliance Service, refer to “Route Compliance Service” on
page 5-24.
4.2.3.2.3 maximumResponses
Some kinds of requests can generate many answers. For example, a POI search
request that specifies a wide search area with a commonplace name part such as
“restaurant” could generate many answers. The maximumResponses attribute limits
the number of responses. Note that this does not mean the number of response
messages but rather the number of “answers” within the response message; one
request always generates exactly one response.
maximumResponses="25"
4.2.4 Responses
The high level format of responses is analogous to that for requests. Rather than a
RequestHeader, there is a ResponseHeader; and rather than a Request, there is a
Response. Most of the rest of the response varies with the type of request and is
explained in the sections on the various core services. One attribute common to all
response types is numberOfResponses.
4.2.4.1 numberOfResponses
numberOfResponses tells the number of “answers” contained in the response.
The following example is from the response to the XML sample code in
Directory01.xml:
numberOfResponses="1">
4-10
October 15, 2010
4.2.4.2 Content-Encoding
When the Content-Encoding: gzip is included in the response, the response is
returned using gzipped (compressed) content. When no Content-Encoding
attribute is present, the response is returned in uncompressed format.
4-11
October 15, 2010
Directory Service (POI Lookups)
4.3 Directory Service (POI
Lookups)
The xml version, XLS, RequestHeader, and ResponseHeader elements of
Directory Service requests and responses are all identical to the standard high level
elements of any XLS request and response, as described in “High Level View of
Requests and Responses” on page 4-4. Figure 4.2 shows the main sub-elements of the
Request element, which distinguish Directory Service requests and responses.
Figure 4.2. The Request/Response Elements of Directory Service Request/Response.
<ns1:POILocation>
<ns1:Nearest>
<ns1:StreetAddress>
</ns1:Address>
</ns1:Nearest>
</ns1:POILocation>
<ns1:POIProperties>
</ns1:Request>
<ns1:POIContext>
<ns2:pos>41.002 -72.0005</ns2:pos>
</ns2:Point>
<ns1:StreetAddress>
ns1:Place>
</ns1:Address>
</ns1:POI>
value="0.082190543709009009076815743810584535822272300720214843
75"/>
</ns1:POIContext>
</ns1:Response>
4.3.1 Requests
The following sections provide some additional explanation of the main elements
shown in the example Directory Service request.
4-12
October 15, 2010
4.3.1.1 methodName
The RequestHeader follows the standard OpenLS format. The outermost level of
the Request also follows the standard OpenLS format. The only variability is that the
methodName attribute’s value specifies that this is a Directory Services request (value
DirectoryRequest).
For example, the outer level of the Request in both sample XML requests
Directory01.xml and Directory02.xml are the following:
<ns1:Request requestID="10" methodName="DirectoryRequest"
...
</ns1:Request>
Of course, in real usage the values of the other attributes will vary.
4.3.1.2 DirectoryRequest
A directory service request will typically specify the location of the POI(s) to be found
and some characteristics of the desired POIs. For example, a request could ask for
restaurants nearest to a street address or POIs of type “museum” in a city. Also, a
deCarta extension allows POIs in a database separate from the RMF datasets to be
queried. A request can also return a count of the number of items that meet a search
criteria.
The DirectoryRequest format uses the elements POILocation,
POIProperties, and database to specify the location, the characteristics of the
desired POIs, and the source data location of the POIs.
4.3.1.2.1 POILocation
POILocation typically specifies that the desired POIs are the closest matching POIs
to an address. This example from Directory01.xml illustrates this usage:
<ns1:POILocation>
<ns1:Nearest>
<ns1:StreetAddress>
</ns1:Address>
</ns1:Nearest>
</ns1:POILocation>
4-13
October 15, 2010
Please refer to the XML schema DirectoryService.xsd for details of ways to
specify the location. The following are the names of the general ways to do so, and the
names are indicative of the kind of location criteria:
•
•
•
•
Address
Nearest
WithinDistance
WithinBoundary
4.3.1.2.2 POIProperties
POIProperties specifies information about the desired POIs, such as name or type,
to use as selection criteria to select from POIs within the POILocation specification.
This example from Directory02.xml specifies that a Keyword for the POI should
have the value restaurant:
<ns1:POIProperties>
<ns1:POIProperty value="restaurant" name="Keyword"/>
A second example from Directory01.xml specifies that the name of the POI
(POIName) should include the word “go-go” (value="go-go"):
<ns1:POIProperties>
<ns1:POIProperty value="go-go" name="POIName"/>
The name attributes of POIProperty elements correspond directly to DDS
keywords:
Name
DDS Keyword
POIName
POINAME
Keyword
POISTRING
Brand
BRAND
Type
TYPESTRING
A POIProperties element may include multiple POIProperty elements. For
example, if you want to find a restaurant named “Muchos” and avoid finding other
kinds of businesses with the same name, you could use a POIProperties element
such as the following:
<ns1:POIProperties>
<ns1:POIProperty value="muchos" name="POIName"/>
<ns1:POIProperty value="restaurant" name="Type"/>
4-14
October 15, 2010
Restrictions on combining POIProperty elements are the same as the restrictions on
combining the equivalent DDS keywords in a DDS query. For details on these DDS
keywords and on the restrictions concerning combining them, please refer to the Drill
Down Server Reference Manual.
When a directory request is directed against a relational database, any number of
POIProperties elements can be used to collectively form a constrained query using
“AND” to combine the POIProperties into an SQL query.
Web Services applies the following strategy to determine how to search the database
for constraints set by POIProperties elements. There are four special
POIProperties names, which are treated differently because the OpenLS POI
element contains explicit attributes to convey these values in returned POIs:
• If the POIProperty name attribute is set to POIName, description, ID, or
phoneNumber (case insensitive), the following applies:
• If the database mapping contains a POIName, Description, ID, or
PhoneNumber element, the columns indicated by said elements will be
searched based on their respective constraints.
• Otherwise, if the database mapping contains a NamedProperty element
whose name matches any of the above, the query will search the “column”
specified in the NamedProperty for the value provided in the POIProperty
element.
• Otherwise, if the database mapping does not contain a relevant
NamedProperty element, the POIProperty name and value attributes will
be used to search a joined table of key/value pairs, as specified by the
StringProperty element in the database mapping.
• Otherwise, if no StringProperty element exists, then the POIProperty is
ignored and the search remains unconstrained
• Otherwise, if the POIProperty name attribute is not one of the four reserved
words, the search will examine NamedProperty elements with matching names.
If no NamedProperty elements exist with matching names, StringProperty
table is consulted, otherwise the POIProperty is ignored.
4.3.1.2.3 ReturnCountOnly
When returnCountOnly is used with the database attribute it will return the count
of the number of items that meet the search criteria. Queries that include the
returnCountOnly attribute must also use the database attribute (these queries work
only with Web Service’s built-in RDBMS support). The results can then be used by an
application to make “heat” maps.
For example, the application can divide the screen into a number of “heat tiles” and
asynchronously get the counts for each tile. The application can use client-side
rendering (via JS API) to shade the tiles according to the “count” value. The
application should then recur into tiles that have more than a threshold number of
4-15
October 15, 2010
items, divide the tile into four inner tiles, and repeat. This produces a recursively tiled
heat map for display in the browser.
4.3.1.2.4 freeformAddrLang
freeformAddrLang specifies that returned addresses are freeform, formatted to the
desired locale. This allows clients to request that the addresses of POIs should be
localized freeform addresses, as opposed to structured addresses. The
freeformAddrLang attribute should be set to match the default MARC language
codes in the RMF data.
The presence of a MARC language code in the POIs name or description will override
the freeformAddrLang attribute. For example, when doing a POI query in Canada,
the freeformAddrLang attribute should be set to EN, since the default MARC
encoding is English. To continue the example, for POIs in Quebec, the presence of
FRE (French) MARC language code will cause the freeform addresses to be formatted
using Canada/French rules.
A file called MARC-to-2letter.properties located in WEB-INF/classes/
com/telcontar/openls/server contains the required translations from MARC
codes to their two-letter OpenLS equivalents. As with the returnFreeForm attribute
of the GeocoderService, address-regex-CC-LC.properties files drive the
construction rules for freeform addresses, where “CC” and “LC” are the ISO ALPHA2
country code and the language code, respectively. Where no properties file exists for a
given country-code and language code, the freeformAddrLang attribute is ignored
and structure result is returned.
For more information on freeform addresses, see “freeFormAddress” on page 4-33
and for more information on address locales, see “Address locales: language +
countryCode” on page 4-32.
4.3.2 Responses
shown in the example Directory Service response.
4.3.2.1 DirectoryResponse
The DirectoryResponse element of the response is directly analogous to the
DirectoryRequest element of the request. It provides all the information about the
found POI(s) that were specified by the DirectoryRequest element.
4-16
October 15, 2010
4.3.2.2 POIContext
The POIContext element returns the information about the POI itself (element POI)
and the context of the POI relative to the POILocation in the request. In the
following example of the response to Directory02.xml the POI element tells about
the POI itself and the Distance element shows the POI’s distance from the location
in the request:
<ns1:POIContext>
<ns1:POI phoneNumber="+(1)-(631)-123-4567"
POIName="PINOCCHIORISTORANTE" ID="0">
<ns2:pos>41.0015 -72.003</ns2:pos>
</ns2:Point>
<ns1:StreetAddress>
<ns1:Street>1st St</ns1:Street>
</ns1:Address>
</ns1:POI>
<ns1:Distance uom="MI" value="0.001"/>
</ns1:POIContext>
4.3.2.2.1 POI
An example of a POI element is shown above in the larger POIContext example.
Typically a POI element has attributes such as phoneNumber and POIName and
elements such as Point and Address. Point uses its nested element pos to report
the latitude and longitude of the POI. Address reports all the available address
information from country down to building number, including all divisions and subdivisions in between.
4.3.2.2.2 Distance
The Distance element reports the POI’s distance from the search point that was
specified in the request, and it reports the units used. A Distance example is
included above in the larger POIContext example.
4-17
October 15, 2010
4.3.2.2.3 Count
The Count element will report the number of items that meet the search criteria.
4.3.3 deCarta Extensions
deCarta provides an extension to easily connect Web Services to an external relational
database of POIs via the existing Directory Service. Web Services maps the POI
element into the relational database.
Figure 4.3. Directory04.xml Request
<ns1:RequestHeader clientPassword="abc123" sessionID="999" clientName="someclient" />
- <ns1:Request version="1.0" methodName="DirectoryRequest" maximumResponses="25" requestID="10">
- <ns1:DirectoryRequest database="StickvillePOIDB">
- <ns1:POILocation>
- <ns1:WithinDistance>
+ <ns1:POI ID="1">
- <ns2:Point xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>41.003 -72.002896</ns2:pos>
</ns2:Point>
</ns1:POI>
<ns1:MaximumDistance value="100" uom="M" />
</ns1:WithinDistance>
</ns1:POILocation>
- <ns1:POIProperties>
<ns1:POIProperty name="description" value="restaurant" />
<ns1:POIProperty name="URL" value="www" />
</ns1:Request>
</ns1:XLS>
This request searches the relational database StickvillePOIDB. Two POIs in the
stickville_poi.txt database meet the criteria of the query.
Figure 4.4. Directory04.xml Response
<ns1:XLS ns1:lang="en" rel="4.1.3sp02" version="1.0" xmlns:ns1="http://www.opengis.net/xls">
<ns1:Response version="1.0" numberOfResponses="0" requestID="10">
<ns1:POIContext>
<ns1:POI ID="undefined" POIName="Stickville Diner" description="RESTAURANT">
<ns1:POIAttributeList>
<ns1:POIInfoList>
<ns1:POIInfo name="URL" value="www.stickvillediner.com"/>
</ns1:POIInfoList>
</ns1:POIAttributeList>
<ns2:pos>41.003 -72.004</ns2:pos>
</ns2:Point>
4-18
October 15, 2010
<ns1:freeFormAddress>1 1st Ave, Stickville, 11111</ns1:freeFormAddress>
</ns1:Address>
</ns1:POI>
<ns1:Distance uom="M" value="57.63"/>
</ns1:POIContext>
<ns1:POIContext>
<ns1:POI ID="undefined" POIName="Joe's Burgers" description="RESTAURANT">
<ns1:POIAttributeList>
<ns1:POIInfoList>
<ns1:POIInfo name="URL" value="www.joesburgers.com"/>
</ns1:POIInfoList>
</ns1:POIAttributeList>
<ns3:pos>41.0029 -72.0021</ns3:pos>
</ns3:Point>
<ns1:freeFormAddress>100 2nd St, Stickville, 11111</ns1:freeFormAddress>
</ns1:Address>
</ns1:POI>
<ns1:Distance uom="M" value="42.31"/>
</ns1:POIContext>
</ns1:Response>
</ns1:XLS>
4.3.3.1 database
The database attribute in DirectoryRequest specifies the db-meta-inf XML
mapping that will be used to instruct Web Services on the layout of the POI database.
The following example is from the sample XML code in Directory04.xml:
<ns1:DirectoryRequest database="StickvillePOIDB">
In the XML above,"StickvillePOIDB" instructs Web Services to use db-metainf/StickvillePOIDB.xml as the database mapping.
To set up your external POI database or to use the sample POI database provided, see
“Setting Up POI Database” on page 3-13.
4.3.3.2 Connection to External Database
To connect to an external database, using a mapping schema described in 4.3.4, you
must provide a javax.sqlDataSource named jdbc/poi. On a Tomcat web server,
this is configured in server.xml. as follows. By default, the database URL points to
the HSQLDB database. The default HSQLDB database is configured with a simple
database of POIs contained in server/hsqldb/poi.txt. HSQL loads this simple
flat file as a TEXT table type. In production deployments, you will likely configure a
more scalable POI database.
<Resource name="jdbc/poi" auth="Container" type="javax.sql.DataSource" />
- <ResourceParams name="jdbc/poi">
4-19
October 15, 2010
- <parameter>
<name>factory</name>
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
- <parameter>
<name>maxActive</name>
<value>10</value>
</parameter>
- <parameter>
<name>maxIdle</name>
<value>5</value>
</parameter>
- <parameter>
<name>maxWait</name>
<value>10000</value>
</parameter>
- <parameter>
<name>username</name>
<value>sa</value>
</parameter>
- <parameter>
<name>password</name>
<value />
</parameter>
- <parameter>
<name>driverClassName</name>
<value>org.hsqldb.jdbcDriver</value>
</parameter>
- <parameter>
<name>url</name>
<value>jdbc:hsqldb:hsql://localhost/olsdb</value>
</parameter>
</ResourceParams>
The web.xml file in Openls/webapp’s is also configured with a resource reference
to the POI DataSource:
- <resource-ref>
<description>DB Connection</description>
<res-ref-name>jdbc/poi</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
Warning: If you want to start a MYSQL database, be sure that you have the
sql-mode turned on with the line sql-mode="ANSI_QUOTES" in your
configuration.
4.3.4 POI Schema
A directory request using the database attribute produces results by searching in an
external relational database. Web Services map the OpenLS PointOfInterestType
into the relational database by consulting a “db-meta-inf” file, created by a Web
4-20
October 15, 2010
Services deployer. The db-meta-inf file may be named anything, but must be
placed in the db-meta-inf folder and must have an “xml” extension.
POISchema.xsd contains the complete XML schema and is located in the directory
install_dir\docs\xml-schema\. POISchema.xsd controls the structure and content
of the db-meta-inf file’s structure.
The schema is designed to allow Web Services to access spatially keyed POIs stored
using a variety of table layouts:
Spatial Key
Spatial key and/or spatial key ranges may be stored in the primary POI table, or may
be linked to the primary POI table through a foreign key in a separate table. This
permits an individual POI to be associated with one or more spatial keys and one or
more spatial key ranges.
Address Information
In DDS Web Services version 4.2.2, address information may be stored in the form of
freeform, but later DDS Web Services versions will support two-line and structured
forms.
1. freeform address
Example:
<xsd:attribute name="single-line-column"/>
2. two-line (not yet supported)
Example:
<xsd:attribute name="line1-column"/>
<xsd:attribute name="line2-column"/>
3. structured (adhering to the OpenLS Address model) (not yet supported)
Example:
<xsd:attribute name="building-locator-column"/>
<xsd:attribute name="street-name-column"/>
<xsd:attribute name="cross-street-name-column"/>
<xsd:attribute name="country-column"/>
<xsd:attribute name="country-subdivision-column"/>
<xsd:attribute name="country-secondary-subdivision-column"/>
<xsd:attribute name="municipality-column"/>
<xsd:attribute name="municipality-subdivision-column"/>
Address information may be stored in the primary POI table, or may be linked to the
primary POI table through a foreign key in a separate table.
POIInfo
POIInfo elements appear in DirectoryRequest in order to place constraints on the
query. For example, <POIProperty name="store-hours" value="9-6"/>
4-21
October 15, 2010
means that the DirectoryRequest is searching for POIs having a property whose
name is “store-hours” and whose property value is “9-6”. The POISchema.xsd uses
the following two mechanisms for telling Web Services how to find properties in the
relational database:
1. The simplest mechanism is the NamedProperty element defined in
POISchema.xsd. For example, a db-meta-inf XML file might contain the
following:
<NamedProperty column="store-hours" name="STORE_HOURS" />
which tells Web Services that the store-hours property is stored in a column named
STORE_HOURS.
2. Alternatively, the db-meta-inf XML file might choose to store name/value pairs
in a linked table, related by a foreign key, as follows:
<StringProperties table="POI_PROPS" join-columns="FK_POI"
name-column="NAME" value-column="VALUE" /> which would tell Web
Services, that to find the “store-hours” property, it should look in the POI_PROPS
table and search for row with “store-hours” in column NAME and “9-6” in column.
Simple Attribute Mapping
The simple attributes POIName, description, and phoneNumber may be mapped
to columns in the primary POI table.
StickvillePOIDB.xml is the sample XML mapping file that conforms to
POISchema.xsd, and is included in the DDS Web Services package.
<POI-Schema xmlns="http://decarta.com/dds/ws/spatialKeyDB" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://decarta.com/dds/ws/spatialKeyDB file:/C:/project/webservices/schema/spatialKeyDB/POISchema.xsd"
table="STICKVILLE_POI">
<SpatialKey singleKey-column="SPATIAL_KEY" />
<Address single-line-column="FREEFORM_ADDRESS" />
<Description column="DESCRIPTION" />
<PhoneNumber column="PHONE" />
<POIName column="POINAME" />
<Latitude column="LATITUDE" />
<Longitude column="LONGITUDE" />
<NamedProperty column="URL" name="URL" />
</POI-Schema>
4.3.4.1 Multi-table External POI Database
The file MultiTablePOIDB.xml is an example file which maps to a more
complicated database layout than the simple Stickville POI database.
MultiTablePOIDB.xml shows that POIs can be populated by joining address
information, spatial keys, and name/value properties and stored in different tables, all
related by foreign keys. Although the tables are not shipped as part of the software
release package, the table creation statements are included as comments in the
MutliTablePOIDB.XML.
4-22
October 15, 2010
4.4 Location Utility Service
(Geocoding and Reverse Geocoding)
Location Utility Service requests and responses are all identical to the standard high
level elements of any XLS request and response, as described in “High Level View of
Request element, which distinguish Location Utility Service requests and responses.
Figure 4.5. The Request/Response Elements of Location Utility Service
Geocode01.xml example request
Geocode01.xml example response
<ns1:Request methodName="GeocodeRequest" requestID="10"
<ns1:GeocodeRequest>
<ns1:StreetAddress>
<ns1:Street>First Ave.</ns1:Street>
</ns1:Address>
</ns1:GeocodeRequest>
</ns1:Request>
<ns1:Response version="1.0" requestID="10" numberOfResponses="1">
<ns1:GeocodeResponse>
<ns1:GeocodeResponseList numberOfGeocodedAddresses="1">
<ns1:GeocodedAddress>
<ns2:pos>41.003 -72.002896</ns2:pos>
</ns2:Point>
<ns1:StreetAddress>
<ns1:Street>1st Ave</ns1:Street>
ns1:Place>
</ns1:Address>
<ns1:GeocodeMatchCode matchType="PATTERN MATCH"
accuracy="1.0"/>
</ns1:GeocodedAddress>
</ns1:GeocodeResponseList>
</ns1:GeocodeResponse>
</ns1:Response>
4.4.1 Requests
shown in the example Location Utility Service request.
4.4.1.1 methodName
The value of methodName is GeocodeRequest for a geocoding request or
ReverseGeocodeRequest for a reverse geocoding request.
4-23
October 15, 2010 Location Utility Service (Geocoding and Reverse
4.4.1.2 GeocodeRequest
The GeocodeRequest element includes one or more Address elements, which
specify the address(es) to be geocoded, and can include the element
returnSpatialKeys, which assigns spatial keys to addresses in a local database. A
GeocodeRequest can also include the deCarta extension attribute
returnFreeForm.
4.4.1.2.1 Address
The Address element specifies one address to be geocoded. You can use either a
structured type address which may use such elements as StreetAddress and
PostalCode, or you can use a “free form address” in a freeFormAddress element.
The freeform address type may save your application the work of parsing a user’s
input or it may save your users the annoyance of manually entering separate elements
of a structured address.
4.4.1.2.2 returnSpatialKeys
The returnSpatialKeys element, when set to TRUE, allows spatial keys to be
assigned to addresses in a local database.
For an example of the returnSpatialKeys element, refer to the sample
Geocode03.xml.
4.4.1.3 ReverseGeocodeRequest
A ReverseGeocodeRequest specifies one or more locations to be reverse
geocoded. It uses Position elements or the streetNumber element to specify the
locations. A ReverseGeocodeRequest can also include the deCarta extension
attributes returnFreeForm.
You can limit the area searched in a ReverseGeocodeRequest by using the
searchRadius element. When the radius is passed in, the reverse geocode is
restricted to that radius, in meters.
4.4.1.3.1 Position
A Position element specifies a latitude and longitude of the location to be geocoded.
4-24
October 15, 2010
4.4.1.3.2 streetNumber
A streetNumber element specifies the street number portion of the address to be
geocoded.
4.4.1.3.3 ReverseGeocodePreference
Unless a request specifies otherwise, a geocode response finds a street, the address
range on the segment of the street, the geopolitical subdivisions of which the location
is a part, and if available, the legal speed limit.
However, you can use a ReverseGeocodePreference element to request
geocoding to the nearest intersection (StreetIntersection element in the
response) or to a specific address (StreetAddress element in the response) instead
of the address range information. Note that StreetAddress is an algorithmic
estimation based on the segment’s address range; since actual addresses may not be
evenly distributed along the segment and not all theoretically possible addresses
actually exist, the result may not be the closest address or even an actual address.
Using the StreetAddress element in the request avoids returning unnamed streets.
For examples of reverse geocoding requests, refer to samples
ReverseGeocode02.xml and ReverseGeocode03.xml.
4.4.2 Responses
shown in the example Location Utility Service response.
4.4.2.1 GeocodeResponse
The GeocodeResponse element returns the results of geocoding the address(es) in
the request. The results appear in GeocodeResponseList elements.
4.4.2.1.1 GeocodeResponseList
The response includes one GeocodeResponseList element for each address in the
request. Each address may have zero, one, or more geocoding matches.
4-25
Note: The GeocodeResponse element is a standard OpenLS feature for geocoding
responses, but is also a deCarta extension when used in a PortrayMapResponse
element. For additional information, see “PortrayMapResponse” on page 4-58.
4.4.2.1.2 GeocodedAddress
A GeocodedAddress element includes a variety of information about a found
location.
Point
A Point element reports the latitude and longitude of the found location. When
geocoding to a city, POINT is now populated with CITY CENTRE (deCarta Uniform
Data Model (UDM) typecode L) for Tele Atlas MultiNet GDF data and PLACE (UDM
typecode D) for NAVTEQ GDF data.
Bounding Box
A BBoxContext element reports the latitude and longitude of opposite corners of the
bounding rectangle.
If you have entered a street address, but the geocoder was unable to find the street
portion of the address, the GeocodeMatchCode response might be “Geography
Pattern Match Not Found” indicating the geocoder was able to find the city, but not the
street.
This behavior accommodates functionality users expect, in web-based mapping
applications such as, if the street address is not found, the map is still positioned on the
municipality portion of the address.
Address
An Address element reports a variety of address-related information about the point.
It can include the same information that appeared in the request (although it may be
parsed differently or more completely) plus additional information about geopolitical
subdivisions that apply to the found location.
When a geocoding operation cannot determine a street address location but it does
successfully find higher level geopolitical divisions, it returns a BoundingBox
element for the geopolitical divisions.
GeocodeMatchCode
The GeocodeMatchCode element reports the type and quality of the match that was
found. The geocoding process can try a multiplicity of strategies to try to find a match
when information is incomplete or does not exactly match. The response information
tells which strategy was finally used to find a match and how good the match is.
4-26
October 15, 2010
Table 4.2 contains the possible values for GeocodeMatchCode when the default
WesternLocaleGeocoder is used. For more information on the
WesternLocaleGeocoder, see “Geocoder Regex Properties File” on page 4-34.
Table 4.2. Descriptions of Values for GeocodeMatchCode
Value
Description
PATTERN MATCH
High confidence pattern matchType for a street
address. When this match code is returned, it
indicates only one DDS query was executed, and a
high quality match was found. The returned
accuracy score gives the pattern match confidence.
STREETNAME PATTERN
MATCH
High confidence pattern matchType for a street
name. A street number was not present in the
input. When this match code is returned, it
indicates only one DDS query was executed, and a
high quality match was found. The returned
STREETNAME SCROLL
When this matchType is returned, the street name
match was poor. Scrolling is only tried as a last
resort after aggressive pattern matching. The
returned accuracy will be set to 1, and should be
ignored, since Soundex matching is not performed
on scrolling.
ADJACENCY SEARCH
Indicates the address was found, but in a different
geography than the user provided. This typically
occurs when the user types in a correct street
address, but the city/neighborhood name is wrong.
Pattern matching is used, and the returned
INFERRED STREET
NUMBER
The street name was correct, but DDS was not
able to find the address and instead returned a
nearby street number that actually exists. Pattern
matching is used, and the returned accuracy score
gives the pattern match confidence.
UNKNOWN STREET
NUMBER IGNORED
The street number could not be found, nor could
any be inferred. No street number returned. Pattern
matching is used, and the returned accuracy score
gives the pattern match confidence.
POSTCODE SEARCH
The geocoder matched the geography by
searching on the postcode.
FULL POSTCODE SEARCH
The geocoder matched a high-precision location
based on an extended/full postcode.
4-27
Value
4-28
Description
AGGRESSIVE
STREETNAME PATTERN
MATCH
An initial DDS pattern match query failed to find
the street name. Therefore, the allowed pattern
match score was reduced, and a second DDS
query was made which returned a result with a
lower pattern match confidence. This match code
generally indicates a result that is still acceptable
to users, but the application may wish to examine
the returned “accuracy” attribute.
AGGRESSIVE
MUNICIPALITY
SUBDIVISION PATTERN
MATCH
This matchType indicates a medium to low
quality pattern match was used to match the input
municipality subdivision. The accuracy will give
the pattern match confidence. Wildcard matching
is used to allow matches when various parts of the
returned address match against the input
municipality subdivision.
MUNICIPALITY SCROLL
This matchType generally indicates a very poor
match. The municipality could not be found by
pattern matching, and scrolling was used. The
returned accuracy will be set to 1, and should be
ignored, since Soundex matching is not performed
on scrolling
MUNCIPALITY
SUBDIVISION SCROLL
match. The municipality subdivision could not be
found by pattern matching, and scrolling was
used. The returned accuracy will be set to 1, and
should be ignored, since Soundex matching is not
performed on scrolling
COUNTRY SECONDARY
SUBDIVISION SCROLL
match. The country secondary subdivision could
not be found by pattern matching, and scrolling
was used. The returned accuracy will be set to 1,
and should be ignored, since Soundex matching is
not performed on scrolling
IGNORE UNMATCHED
ZIPCODE
This matchType is common, and indicates the
postal code entered by the user was incorrect.
Pattern matching is used on the street name and
the city name, and the returned accuracy gives the
quality of the street name pattern match, if street
name was present in the input, otherwise the
accuracy gives the pattern match score of the
municipality.
October 15, 2010
Value
Description
GEOGRAPHY PATTERN
MATCH
This matchType is returned if either a city was
entered without street address information, or the
street address information had to be dropped
because multiple matching techniques failed to
find the street address. It is common for mapping
applications to provide a map of the city when the
street name could not be found, and this match
code can be used to identify cases when the street
could not be found.
AGGRESSIVE GEOGRAPHY
PATTERN MATCH
An initial DDS geography pattern match query
failed to find the geography with a high quality
match. Therefore, the allowed pattern match score
was reduced, and a second DDS query was made
which returned a result with a lower pattern match
confidence. This match code generally indicates a
result that is still acceptable to users, but the
application may wish to examine the returned
‘accuracy’ attribute.
AGGRESSIVE
MUNICIPALITY PATTERN
MATCH
This matchType indicates a medium to low
quality pattern match was used to identify the city.
The accuracy will give the pattern match
confidence. Wildcard matching is used to allow
matches when various parts of the returned
address match against the input municipality.
COUNTRY SECONDARY
SUBDIVISION PATTERN
MATCH
This matchType indicates that the input
contained a country secondary subdivision (in the
USA, this is a county), and that a high quality
pattern match was found. Wildcard matching is
used to allow matches when various parts of the
returned address match against the input
COUNTRY SECONDARY SUBDIVISION.
MUNICIPALITY
SUBSTITUTED WITH
COUNTRY SECONDARY
SUBDIVISION
This matchType indicates that the user provided a
country secondary subdivision (in the U.S. this is a
county), but that the provided country secondary
subdivision was actually the name of a city.
MUNICIPALITY
SUBSTITUTED WITH
MUNICIPALITY
SUBDIVISION
This matchType indicates that a municipality
match was found, but it was found by using the
municipality subdivision (in the USA, this is a
neighborhood name) as the city name.
4-29
Value
4-30
Description
COUNTRY SECONDARY
SUBDIVISION
SUBSTITUTED WITH
MUNICIPALITY
This matchType indicates that a match was found
by using the provided country secondary
subdivision as the municipality.
COUNTRY SECONDARY
SUBDIVISION
SUBSTITUTED WITH
MUNICIPALITY
SUBDIVISION
This matchType indicates that a match was found
by using the provided country secondary
subdivision as the municipality.
CROSS STREET PATTERN
MATCH
This matchType indicates a high quality pattern
match was found, in a single DDS query, for a
cross street address.
CROSS STREET SCROLL
This matchType indicates a cross street was
found using scrolling. This indicates a low quality
match for the cross street. The returned accuracy
will be set to 1, and should be ignored, since
Soundex matching is not performed on scrolling
AGGRESSIVE CROSS
STREET PATTERN MATCH
An initial DDS pattern match query failed to fine
the cross street. Therefore, the allowed pattern
match score was reduced, and a second DDS
query was made which returned a result with a
lower pattern match confidence. This match code
generally indicates a result that is still acceptable
to users, but the application may wish to examine
the returned 'accuracy' attribute.
ALTERNATE CROSS
STREET NAMES
The cross street could not be found, therefore, a
complete set of actual cross street intersections is
returned for the primary street.
GEOGRAPHY EXACT
MATCH
This matchType is reserved, and is not presently
returned.
NO MATCH
No match could be found. All match techniques
were tried and exhausted, including pattern
matching, scrolling, adjacency, inferencing, etc.
UNKNOWN_STREET_IGNOR
ED
The street name was dropped because it could not
be found in the requested geography, using a
variety of match techniques. No adjustments were
made to the geography match technique.
October 15, 2010
Value
Description
LANDMARK SEARCH
For a geocode request with a freeform address,
when the address does not contain any commas, an
LPOI is performed first to find out whether it is a
landmark or not. This type of search can also be
controlled through the address-regex-CCLC.properties file by setting the attribute
"perform-landmark-search" to TRUE or
FALSE.
FULL POSTCODE AND
PATTERN MATCH
When an address contains a full postal code and
street information, a centroid search for the full
postal code is performed.
SHORTEN POSTCODE AND
PATTERN MATCH
When the “full postcode and pattern match”
method fails, the postal code is shortened and a
pattern match is performed with Scroll for the
postal code.
Please refer to the Drill Down Server Reference Manual for additional details about
those match methods.
The list of values is not in any specific order; in particular, it doesn’t indicate a search
strategy sequence. In general, the search resolves the geography (higher level entities
such as state, province, city) first and then the street address. Any result with SCROLL
in the GeocodeMatchCode is likely to be a poor match since scrolling is a last resort.
4.4.2.2 ReverseGeocodeResponse
The ReverseGeocodeResponse element provides information about each reverse
geocoded location. ReverseGeocodeResponse includes
SearchCentreDistance.
4.4.2.2.1 ReverseGeocodedLocation
The ReverseGeocodedLocation element provides Point, Address,
returnSpatialKeys elements, which have already been described, for each
specified location.
4-31
4.4.2.2.2 SearchCentreDistance
The SearchCentreDistance element returns the distance from the point in the
request to the address(es) returned by the geocoder. The unit of measure is determined
by the server.
4.4.2.2.3 StreetAddress
The StreetAddress element returns building number and legal speed limit for that
street.
4.4.2.2.4 streetNumber
The streetNumber elements returns OffsetLL attribute, the latitude and longitude
offset to the side of the road from the found location, and a sideofStreet attribute,
which reports on the side of a given polyline the found feature lies.
deCarta has created extensions to make it easier for an application to geocode an
address, to localize geocoding for countries and languages, and to save processing
steps when geocoding is only an ancillary function in performing a larger function; for
example, geocoding an address may be necessary to determine the center point for
drawing a map or to determine start and end points for a route. deCarta’s extensions
make it easy to include the ancillary geocoding within the request that performs the
real desired function of drawing a map or calculating a route.
4.4.3.1 Address locales: language + countryCode
In the OpenLS specification, the Address complex data type has an attribute
countryCode. deCarta extended the specification to allow an additional attribute
language. We call a combination of countryCode and language a “locale.”
You can see examples of using locales in the Web-based console on the Driving
Directions, GeocoderFreeForm, and GeocoderStructured tabs. Each of those
tabs has a selection box with options such as US-EN (USA, English language), FR-FR
(France, French language), CA-EN (Canada, English), and CA-FR (Canada, French).
The application uses your selection to create an Address element with appropriate
attributes.
4-32
October 15, 2010
For example, if you select US-EN as your locale on the GeocoderFreeForm tab, the
application creates an Address such as this one:
<ns1:Address language="EN" countryCode="US">
<ns1:freeFormAddress>...</ns1:freeFormAddress>
</ns1:Address>
Note: Specifying a locale that does not match the dataset is allowed; however, the
results may be erroneous or unexpected, particularly in parsing a freeFormAddress
element, which is described in “freeFormAddress” on page 4-33. For example, if you
specify country U.S. and language German (or vice versa), you will probably get very
disappointing results, unless you have a very unusual dataset.
This extension to the Address complex data type is described here in the geocoding
section of this chapter, but since it is a data type that can be used in other kinds of
requests (particularly drawing maps and calculating routes), it is applicable to those
kinds of requests too, wherever an Address element can appear.
4.4.3.2 freeFormAddress
The freeFormAddress element in a geocoding request allows you (or your users) to
enter an address as a single line of information rather than parsing or breaking it into
smaller, more structured pieces. The DDS Web Services “freeform geocoder” can try a
multiplicity of techniques to parse and interpret the input line. It can match normal
complete addresses, intersections, and some incomplete addresses.
4.4.3.3 parserReport
The parserReport is a GeocodeRequest attribute used in conjunction with a
freeform address. When a parserReport is requested, a parserReport element
within the GeocodeReponseList is returned. The parserReport element contains
an Address which is a structured version of the freeform address entered by the user.
At an application level, you can show a user the various components of the address the
user entered, allowing for corrections to mistakes made by the parser from missing
punctuation, misspellings, or incomplete or incorrect addresses.
The parserReport attribute is also useful if an application wants to create a hybrid
freeform-to-structured input form where the user enters a one-line freeform address
which is automatically parsed into a structured address, giving the user an opportunity
to correct any parsing errors before the geocoding is performed.
The parserReport attribute has no effect in a structured geocode request.
4-33
4.4.3.4 parseOnly
When the parseOnly attribute is set to “true”, only the input freeform address is
parsed and no geocoding is performed.
The parseOnly attribute has no effect in a structured geocode request. For an
example of the parserReport and the parseOnly element, refer to the sample
Geocode04.xml.
4.4.4 Geocoder Regex Properties File
The freeFormAddress element of the response can show a freeform address rather
than the list of geopolitical subdivisions. The geocoder regex properties files
(address-regex-CC-LC.properties ) contain rules to localize the formatting
(token ordering) of freeFormAddress elements, according to country code (CC) and
language code (LC). The address-regex-CC-LC.properties file allows a
specific geocoder state machine to be specified. By default, the address-regexCC-LC.properties files contain the default geocoder state machine:
GeocoderStateMachine=WesternLocaleStateMachine
The geocoder state machine (“geocoder”) provides even more control over the
geocoding process. Different locales such as CA-FR (Canada, French) require
“tuning” of the geocoder state machine and sometimes, a completely different
sequence of states. Potentially, a different geocoder state machine may be used for
each locale. For more information on the geocoder state machine see “Geocoder State
Machine” on page 4-35.
The GeocodeRequest includes a deCarta extension called returnFreeForm. This
allows the request to tell the server if addresses should be returned in a structured or
freeform format. If the returned address is freeform, the server honors a set of rules for
how freeform addresses are formatted. The control of freeform address formatting is
determined by token ordering section of the address-regex-CC-LC.properties
file for the locale of the address. For example, the following token ordering section of
address-regex-IT-IT.properties controls the formatting of freeform
addresses for addresses located in Italy. This example results in freeform addresses for
Italy including a street name, followed by street number, followed by city, followed by
postal code. Municipality subdivisions and country subdivisions are omitted, since
they do not commonly appear in Italian addresses.
# specify the token order used to RETURN freeform
addresses
#########################################################
street-name-token-order=0
#street-name-separator=,
street-number-separator=,
street-number-token-order=1
4-34
October 15, 2010
#municipality-subdivision-separator=,
#municipality-subdivision-token-order=2
municipality-separator=,
municipality-token-order=3
postal-code-separator=,
postal-code-token-order=4
#country-secondary-subdivision-separator=,
#country-secondary-subdivision-token-order=4
#country-subdivision-separator=,
#country-subdivision-token-order=
When you use the freeform geocoder, the response will include a
GeocodeMatchCode element which reports to you the type and quality of match that
was made. For a list of the possible match types, please refer to “GeocodeMatchCode”
on page 4-26. The response will also include a report element, which is described in
“report” on page 4-37.
If the geocoder cannot find a street address, it will still attempt to find a municipality
or other higher level geographic subdivision.
4.4.5 Geocoder State Machine
The geocoder state machine defines the strategy that Web Services uses to geocode an
address or location. The following sections describe how to understand, modify, or
create a geocoder state machine. In reality, a geocoder state machine may (and usually
does) contain multiple state machines within it; therefore, to avoid confusion, this
discussion will generally refer to the top-level geocoder state machine as simply the
geocoder and will use the term “state machine” to refer to one of its component state
machines.
4.4.5.1 Introduction to the Geocoder
The Web Services geocoder performs a sequence of DDS Lookup queries to geocode
an input address. Depending on the quality of the input address, Web Services may
perform multiple queries to return a geocoded result. Within the geocoder,
adjustments may be made to each query, such as adding adjacency (ADJACENCY
SEARCH) or modifying the acceptable pattern match score.
Each time the geocoder executes a DDS Lookup query, it examines the DDS response
message. If the status in the response is “OK,” then the geocoding has succeeded and
no further queries are generated. Otherwise, the geocoder uses the status message to
determine what to do next, according to the geocoder’s defined strategy. “What to do
next” means to move to a different state or even to a different state machine. If the
4-35
geocoder gets to a point where the defined strategy has no further options to try, then
the geocoding has failed.
A strategy takes into consideration the kinds of input provided and the status messages
returned from DDS queries. It determines the changes to make in follow-up DDS
queries. Changes may include adding or removing DDS keywords, changing the value
of DDS keywords, and changing the DDS query token used. Creating or working with
a geocoder clearly requires knowledge of the DDS Lookup plug-in, its queries, and its
keywords. For detailed information about these subjects, refer to the Drill Down
Server Reference Manual. This discussion assumes such knowledge.
A geocoder is defined in an XML file. The XML schema file
GeocoderStateMachine.xsd defines the content of a geocoder XML file; this
discussion will explain the content in a much more informal way, primarily using
examples.
Different locales require different geocoding strategies because of differences in
address forms in various countries, differences in the ways people write addresses
(particularly inexact and incomplete addresses), language differences, and various
other sorts of differences. Therefore, Web Services allows for using a different
geocoder for each locale.
Each locale’s regex properties file address-regex-CC-LC.properties specifies
which geocoder to use for that locale. A line in the regex properties file such as
GeocoderStateMachine=geocoderName means to use the geocoderName.XML file as
that locale’s geocoder. For example, if
GeocoderStateMachine=WesternLocaleStateMachine is in an addressregex-CC-LC.properties file, Web Services uses the geocoder defined by
WesternLocaleStateMachine.xml.
All the regex properties files are in the directory install_dir\Web
Services\server\Tomcat 5.0\webapps\openls\WEBINF\classes\com\telcontar\openls\server. All the geocoder XML files are
in the directory install_dir\Web Services\server\Tomcat
5.0\webapps\openls\WEBINF\classes\com\telcontar\openls\server\geocoder\statemachines.
Web Services ships with many geocoders, some of which include the following:
1. WesternLocaleStateMachine.xml
2. FranceGeocoder.xml, which is used in conjunction with address-regex-frfr.properties
3. GreatBritainGeocoder.xml, which is used in conjunction with addressregex-GB-EN.properties
4. GermanyGeocoder.xml, which is used in conjunction with address-regexDE-DE.properties.
5. USAGeocoder.xml, which is used in conjunction with address-regex-USEN.properties.
4-36
October 15, 2010
6. HelloWorld.xml, which is a very simple geocoder example used to begin
learning.
Refer to the directory install_dir\Web Services\server\Tomcat
5.0\webapps\openls\WEBINF\classes\com\telcontar\openls\server\geocoder\statemachines
for a complete list.
4.4.5.2 report
A report element reports the complete DDS query and response that found the
results. This element can be useful in detailed testing and debugging, by showing the
details of internal communication between the geocoder and the DDS.
You can request that the response include a report element by including a
report=true attribute in the request. Use the GeocoderFreeForm tab of the webbased console to see examples.
The following shows a complete example report element (long lines broken for
readability) returned from geocoding the freeform address “2nd & santa clara, san jose
ca”:
<ns1:Report>
**********************************************************************
** DDS QUERY
** LXST|%G0=USA%G1=CA%G9=san jose%SN=2nd%XSN=santa clara
%CUST=telcontar-db|%GZ%AZ%G6%SN%XSN%XLL
%QSN=PAT,75%QXSN=PAT,75%UGEOCODE_TACTIC=CROSS STREET PATTERN MATCH
%S%M=1000%EXTIME%DS=navteq||
**********************************************************************
**********************************************************************
** DDS RESPONSE
** LXST|%EXTIME=40%UGEOCODE_TACTIC=CROSS STREET PATTERN MATCH%N=1%S=OK
|%G0=USA%G1=CA%G2=SANTA CLARA%G4=SAN JOSE%G6=95113%SN=N 2ND ST
%PSN=80%XSN=E SANTA CLARA ST%PXSN=85%XLL=37.33666,-121.88950||
**********************************************************************
</ns1:Report>
4.4.5.3 Structure and Organization of a Geocoder
A geocoder always works with a structured address. In the case of using a freeform
address, the geocoding parser creates a structured address by parsing the tokens in the
freeform address, according to rules for the locale defined in the regex properties file.
4-37
Any geocoder contains at least one state machine, usually several. Each state machine
has at least one state, usually more. A geocoder also has an entry point (EntryPoint
element) that typically determines which state machine within the geocoder to activate
first. The diagram in Figure 4.6 shows an example of the structure of a geocoder.
Figure 4.6. Diagram of the WesternLocaleStateMachine.
WesternLocaleStateMachine
Entry Point
StreetAddress
A
B
Intersection
StreetAddress
C
Geography
D
E
In this example, the WesternLocaleStateMachine.xml file defines the
WesternLocaleStateMachine geocoder, which contains an entry point and the three
state machines StreetAddress, IntersectionStreetAddress, and
Geography. The circles with letters A through E represent states within the state
machines, but they are not the real names of states. Each state machine also has an
Initialization state; to keep the diagram simple, the Initialization states are
not shown.
In the WesternLocaleStateMachine geocoder, the entry point examines which kinds of
input are available and chooses an initial state machine accordingly. For example, if
the input includes what appears to be a complete address such as “123 Post St., San
Jose, CA”, it chooses the StreetAddress state machine. If it is an intersection such
as “Hollywood & Vine, Hollywood, CA”, it chooses the
IntersectionStreetAddress state machine. If it appears to have no street
information, then it chooses the Geography state machine to lookup a city.
4-38
October 15, 2010
Whenever a state is active, it executes at most one DDS query. Some states do not
execute any queries. Typically, a state sets up all or part of a DDS query by doing
some of the following: setting or changing the query token, adding or removing
keywords, or changing the values of keywords. When a state finishes all its query
setup, then the geocoder sends the query to the DDS and receives the response from
the DDS.
If the response’s status is “OK”, then geocoding is complete. Otherwise, the geocoder
determines which state machine and which state within that state machine to access
next. How that selection is made is explained further in the remaining parts of this
discussion. At this point, it is sufficient to realize that, depending on the status
returned by DDS, on the available inputs, and on the strategy defined in the geocoder,
it is possible for the next action to be further processing of the same state, going to a
new state within the same state machine or going to a state in a different state machine.
For example, one geocoding process could go through the following sequence of
states: state A in StreetAddress, then state D in Geography, then state E in
Geography , and then state B back in StreetAddress. When a state transition goes
from one state machine to another, as in going from A to D, we call it a “lateral
transition.”
4.4.5.4 The SimpleDemo Example Geocoder
Now it is time to begin looking at the details. Most of the concepts involved are easier
to understand from looking at examples than from formal, theoretical explanations.
Therefore, this discussion concentrates on specific examples, which you will easily
generalize. To find the theoretical details, refer to the XML schema file
GeocoderStateMachine.xsd.
In order to make more understandable examples, this discussion uses a relatively
simple geocoder which we will call SimpleDemo. The SimpleDemo geocoder is really
a much-simplified version of the WesternLocaleStateMachine geocoder. It was
simplified by removing all but two of the state machines, removing many of the states
from the remaining state machines, and removing various elements whenever possible
to make it shorter and simpler, while still functioning reasonably well for illustrative
cases.
The SimpleDemo geocoder is defined in file SimpleDemo.xml. (This file is not in
the software distribution.) It is to be used in conjunction with the regex properties file
address-regex-US-EN.properties, so you can see that it is intended to be used
with USA addresses in English. Here is a complete listing of this file, followed by a
diagram of its components in Figure 4.7:
<?xml version="1.0" encoding="UTF-8"?>
<Geocoder xmlns='http://decarta.com/dds/webservices/geocoder'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://decarta.com/dds/webservices/geocoder
4-39
file:/C:/project/webservices/schema/geocoder/
GeocoderStateMachine.xsd'>
<EntryPoint execute-query="false">
<NextState if-inputcontains="SN">SimpleDemo.StreetAddress.initialization</NextState>
<NextState>SimpleDemo.Geography.initialization</NextState>
</EntryPoint>
<StateMachine name="StreetAddress" driven-by="street name not
found.*">
<EntryPoint name="initialization" execute-query="false" querytoken="LADR">
<NextState>SimpleDemo.StreetAddress.patternMatch</NextState>
</EntryPoint>
<State name="patternMatch">
<Input name="G0">${G0}</Input>
<Input name="G1" if-input-contains="G1">${G1}</Input>
<Input name="SN">${SN}</Input>
<Input name="NO" if-input-contains="NO">${NO}</Input>
<Control name="UGEOCODE_TACTIC">PATTERN MATCH</Control>
<Control name="QSN">PAT,90</Control>
<Control name="LL"/>
<Control name="GZ"/>
<Control name="QG1" if-input-contains="G1">PAT,80</Control>
<NextState if-status=".*not found in
geography">SimpleDemo.StreetAddress.adjacency01</NextState>
<NextState>SimpleDemo.StreetAddress.aggressivePatternMatch</
NextState>
</State>
<State name="aggressivePatternMatch">
<Control name="UGEOCODE_TACTIC">AGGRESSIVE STREETNAME
PATTERN MATCH</Control>
<NextState if-status=".*not found in
geography">SimpleDemo.StreetAddress.adjacency01</NextState>
<NextState>SimpleDemo.StreetAddress.removeStreetLevelInfo</
NextState>
</State>
<State name="adjacency01">
<Control name="ADJ">K10</Control>
<Control name="UGEOCODE_TACTIC">ADJACENCY SEARCH</Control>
<NextState>SimpleDemo.StreetAddress.removeStreetLevelInfo</
NextState>
4-40
October 15, 2010
</State>
<State name="removeStreetLevelInfo" execute-query="false">
<Remove>
<Input name="SN"/>
<Input name="NO"/>
<Control name="SN"/>
<Control name="QSN"/>
<Control name="VR"/>
</Remove>
<NextState querytoken="LGEO">SimpleDemo.Geography.$RESUME_STATE</NextState> 
</State>
</StateMachine>
<StateMachine name="Geography" driven-by="Geography not found">
<EntryPoint name="initialization" execute-query="false" querytoken="LGEO">
<NextState
if-input-contains="G1|G2|G4|G5">SimpleDemo.Geography.placeSearch</
NextState>
</EntryPoint>
<State name="placeSearch">
<Control name="Utrace2"/>
<Control name="UGEOCODE_TACTIC">GEOGRAPHY PATTERN MATCH</
Control>
<Control name="LLMIN"/>
<Control name="LLMAX"/>
<Control name="G0"/>
<Control name="G1"/>
<Control name="G2" if-input-contains="G2|G4|G5"/>
<Control name="G4" if-input-contains="G4|G5"/>
<NextState
4-41
if-inputcontains="G1|G2|G4|G5">SimpleDemo.Geography.aggressivePlaceSearch</
NextState>
</State>
<State name="aggressivePlaceSearch"
extends="SimpleDemo.Geography.placeSearch">
<Control name="UGEOCODE_TACTIC">AGGRESSIVE GEOGRAPHY PATTERN
MATCH</Control>
</State>
</StateMachine>
</Geocoder>
Here is a diagram of the states and state machines in SimpleDemo:
Figure 4.7. Diagram of the SimpleDemo Geocoder.
Entry Point
StreetAddress
initialization
Geography
initialization
patternMatch
placeSearch
aggressivePatternMatch
adjacency
aggressivePlaceSearch
removeStreetLevelInfo
4-42
October 15, 2010
4.4.5.5 Examples Using the SimpleDemo Geocoder
The following examples were executed using the GeocoderFreeForm tab of the webbased console. They heavily use the report function (“report” on page 4-37) to
examine the DDS queries and responses generated in the geocoding process.
Wherever a red letter and number such as B-2 appears in report output, it is not
really part of the report output. Rather, it is inserted to make easy references to
queries and responses in the explanations of the examples.
Example A: Completely good address
This example uses a completely good and exact address:
610 grand fir ave, sunnyvale, ca
report output:
**********************************************************************
** DDS QUERY A-1
**
LGEO|%G0=USA%UGEOCODE_TACTIC=VALIDATE_CITY%G9=sunnyvale%CUST=someclien
t|%QG9=PAT,65%M=1%EXTIME%DS=NT%CHARACTERENCODING=iso-8859-1||
**********************************************************************
**********************************************************************
** DDS RESPONSE A-1
**
LGEO|%EXTIME=47%UGEOCODE_TACTIC=VALIDATE_CITY%N=1%O=17%S=OK|%G0=USA%G1
=CA%G2=SANTA CLARA%G4=SANTA CLARA%G5=SUNNYVALE%G6=94089%PG=100||
**********************************************************************
**********************************************************************
** DDS QUERY A-2
** LADR|%G0=USA%G1=CA%G4=sunnyvale%SN=grand fir
ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=PATTERN
MATCH%QSN=PAT,90%LL%GZ%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARAC
TERENCODING=iso-8859-1||
**********************************************************************
**********************************************************************
** DDS RESPONSE A-2
** LADR|%EXTIME=390%UGEOCODE_TACTIC=PATTERN
MATCH%N=1%S=OK|%G0=USA%G1=CA%G2=SANTA
CLARA%G4=SUNNYVALE%G6=94086%PG=100%SN=GRAND FIR
AVE%PSN=100%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305||
**********************************************************************
4-43
Discussion of the results:
The discussion of this first example goes into much more detail than subsequent
examples, in order to begin with a fairly complete explanation of the most basic
aspects of the geocoder. Subsequent examples will generally discuss only what is new
for that example.
The first query A-1 is actually generated by the parser, not by the geocoder. The
parser generates DDS queries to validate its parsing of the input before it passes its
structured address information to the geocoder. It uses the user-defined keyword
%UGEOCODE_TACTIC=VALIDATE_CITY to identify its query. In subsequent
examples, the discussion will not list the parser’s validation queries.
The first query generated by the SimpleDemo geocoder is A-2. Here is how that
query is created:
The geocoder begins at the entry point. The relevant text from the beginning of the
XML file is this:
<EntryPoint execute-query="false">
<NextState if-input-contains="SN">
SimpleDemo.StreetAddress.initialization</NextState>
<NextState>SimpleDemo.Geography.initialization</NextState>
</EntryPoint>
The EntryPoint will not execute a DDS query because of the executequery="false" attribute. This is typical for an EntryPoint and for
initialization states. Without that attribute, a state will execute a DDS query, but
in this case, no parts of a DDS query have even been set up yet.
The next step in processing is the <NextState if-input-contains="SN">
element. The meaning here is what seems fairly obvious. The if-inputcontains attribute tests whether the input (from the structured address information)
contains a street name (SN is the DDS keyword for street name.); if it does contain a
street name, then it uses the NextState value
SimpleDemo.StreetAddress.initialization as the next state to go to.
Since our input does contain a street name (“grand fir ave”), it goes to
StreetAddress.initialization as the next state. (If there were no street
name in the input, then it would fall through to the next <NextState> element and
go unconditionally to the Geography state machine’s initialization state.)
The initialization state is another rather simple state, defined by these lines from
the XML file:
<EntryPoint name="initialization" execute-query="false" querytoken="LADR">
<NextState>SimpleDemo.StreetAddress.patternMatch</NextState>
</EntryPoint>
This state also does not execute a DDS query because of the executequery="false" attribute. It does, however, begin to build a DDS query by setting
4-44
October 15, 2010
the query token to LADR (lookup address). The geocoder builds a DDS query, bit by
bit, in an internal buffer. After it puts something into its working DDS query, that part
of the query remains there until an action specifically removes it or changes it, even
through state transitions and even when switching to a different state machine within
the geocoder. If you look at the first non-parser query A-2, you will see that its query
token is LADR, as the initialization state set it.
After setting the query token to LADR, the next step is the unconditional NextState
transition to the StreetAddress.patternMatch state. The patternMatch
state begins with a number of Input and Control elements. We will look at only a
few of these in detail because the pattern will become obvious. Input elements set up
DDS input keywords in the query that is being built; Control elements set up control
keywords in the query.
A few of those elements from the patternMatch state are these:
<Control name="UGEOCODE_TACTIC">PATTERN MATCH</Control>
The line that contains G0 sets up a G0 input keyword with value specified by ${G0}.
The form ${xx} means the value passed in from the parser for keyword xx. The parser
always knows the value for G0 (country), even if the input doesn’t contain it, because
it is inherent in the regex properties file for a locale (country plus language). Looking
at the query A-2, you can see the input keyword set up by this line, %G0=USA.
The G1 line creates a G1 input keyword only if the parser isolated a state. In this case
the keyword is %G1=CA.
The UGEOCODE_TACTIC creates a user-defined keyword that identifies the tactic
currently being tried by the geocoder. In the deCarta-provided geocoders, all states
that execute a DDS query also contain a UGEOCODE_TACTIC keyword that uniquely
identifies the state which generated this query. Your application can use this output to
identify the type of match that was found by the geocoder.
The QSN line sets up a QSN keyword with value PAT,90. That is, the keyword-value
pair is %QSN=PAT,90. This means that the geocoder wants a pattern-match score of at
least 90 for matching the street name.
The LL line, with no value, simply generates a control keyword %LL, with no value, to
request that the response return the latitude and longitude of the geocoded address.
You might want to look at the other Input and Control elements in the
patternMatch to verify for yourself that they appear in the A-2 query.
After all the input and control lines, the next line in patternMatch is a NextState
element. This tells the geocoder that all the set up is complete and it is now time to
send the query to the DDS. It sends the A-2 query and receives back the A-2
4-45
response. Since the status in the response is “OK”, the geocoding succeeded and is
complete; the geocoder does no further processing for this address. The LL keyword in
the response is the geocoded location. Various other output keywords report other
information about the found location.
Example B: Incorrect and incomplete street address
This example uses an incorrect (“fir” is misspelled) and incomplete (“ave” is missing)
street name:
610 grand fur, sunnyvale, ca
report output:
**********************************************************************
** DDS QUERY B-1
** LADR|%G0=USA%G1=CA%G4=sunnyvale%SN=grand
fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE B-1
** LADR|%EXTIME=203%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Street name not
found||
**********************************************************************
**********************************************************************
** DDS QUERY B-2
** LADR|%G0=USA%G1=CA%G4=sunnyvale%SN=grand
fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME
PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE B-2
** LADR|%EXTIME=219%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME PATTERN
MATCH%N=2%S=OK|%G0=USA%G1=CA%G2=SANTA
AVE%PSN=82%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305|%G0=USA%G1=CA%G2=SANTA
CLARA%G4=SUNNYVALE%G6=94087%PG=100%SN=LA GRANDE
DR%PSN=71%VR=2,3733841,-12203978,0,218%AR=698 - 608%LL=37.338409,122.037760||
**********************************************************************
4-46
October 15, 2010
This example starts in the same way as example A and proceeds the same until the
patternMatch state sends the query B-1. The only difference is the value of SN
keyword, because the input street name is slightly different.
This time, however, the geocoding query fails and the response B-1 has the status
%S=Street name not found. The next step can be a bit confusing and mysterious,
at first. Although the geocoder was in the patternMatch state, just before the first
NextState element, when it sent the query, that is not where the processing resumes
for the next step.
When the query fails, the geocoder uses the status message to determine which state
machine to use next. The selection of a state machine is “driven by” the driven-by
attributes of the state machines, which appear in the first line of the state machines’
definitions. In SimpleDemo, the relevant lines for the two state machines are these:
<StateMachine name="StreetAddress" driven-by="street name not found.*">
...
<StateMachine name="Geography" driven-by="Geography not found">
The values in the driven-by attributes are regular expressions used to match the
status message. If the status message were Geography not found, it would cause a
lateral transfer to the Geography state machine. (A later example looks at this case.)
If the status message is either Street name not found or Street name not
found in geography, it matches the driven-by attribute for the
StreetAddress state machine. Since the B-1 response status is Street name not
found, the geocoder will go (come back) to the StreetAddress state machine.
If the status message did not match the driven-by attribute for any state machine,
then the geocoder would have nowhere to go next and geocoding would fail. In fact,
with the incomplete geocoder SimpleDemo, if the response status were, for example,
Address not found, then geocoding would fail.
4-47
The driven-by attribute is so important in determining the sequence of states through
which the geocoder passes, that it seems worthwhile to update our diagram of
SimpleDemo to include that information:
Figure 4.8. Diagram of the SimpleDemo Geocoder, with driven-by Attribute.
Entry Point
StreetAddress
driven-by= "street name not found.* "
Geography
driven-by=”Geography not found”
initialization
initialization
patternMatch
placeSearch
aggressivePatternMatch
adjacency
aggressivePlaceSearch
removeStreetLevelInfo
The B-1 response status and the driven-by attribute cause the geocoder to
return to the StreetAddress state machine. Since the StreetAddress state
machine has already been used, it returns to the same state where it last was; that is, in
patternMatch state after setting up inputs and control and just before examining the
first NextState element.
The remaining lines in the patternMatch state are these:
<NextState if-status=".*not found in geography">
SimpleDemo.StreetAddress.adjacency01</NextState>
<NextState>SimpleDemo.StreetAddress.aggressivePatternMatch</NextState>
Since the status message is Street name not found (without in geography),
the if-status= condition of the first NextState element is not met. Therefore, it
4-48
October 15, 2010
falls through to the next NextState element and goes unconditionally to the
StreetAddress.aggressivePatternMatch state.
The aggressivePatternMatch state is fairly simple. It has only the following two
control keyword lines (plus one NextState element):
<Control name="UGEOCODE_TACTIC">AGGRESSIVE STREETNAME PATTERN MATCH
</Control>
<NextState...>
These lines change the values of two control keywords, making the required street
name match quality less restrictive (match score of 65 instead of 90 as it was in the
B-1 query) and changing the user-defined keyword to show the current tactic. The
end of input and control keywords, indicated by the NextState element, means that
it is now time to send the next query to the DDS. If you examine the B-1 and B-2
queries, you can see that the only difference is the values of those two keywords.
The B-2 response shows a status of “OK” so the geocoding succeeded. In fact, with
the relaxed match score requirement, the DDS actually found two qualifying
addresses, the one we want and another on La Grande Dr. La Grande Dr’s match score
(71) is considerably less than Grand Fir Ave’s score (82). This example shows that
your application will need a strategy to deal with such cases of multiple possible
matches.
Example C: Wrong, but adjacent, city
This example uses a wrong, but adjacent, city as people sometimes do when they don’t
know where city boundaries are:
610 grand fir ave, santa clara, ca
report output:
**********************************************************************
** DDS QUERY C-1
** LADR|%G0=USA%G1=CA%G4=santa clara%SN=grand fir
**********************************************************************
**********************************************************************
** DDS RESPONSE C-1
found in geography||
**********************************************************************
**********************************************************************
** DDS QUERY C-2
** LADR|%G0=USA%G1=CA%G4=santa clara%SN=grand fir
ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=ADJACENCY
4-49
SEARCH%QSN=PAT,90%LL%GZ%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARA
CTERENCODING=iso-8859-1%ADJ=K10||
**********************************************************************
**********************************************************************
** DDS RESPONSE C-2
** LADR|%EXTIME=203%UGEOCODE_TACTIC=ADJACENCY
SEARCH%N=1%S=OK|%G0=USA%G1=CA%G2=SANTA
AVE%PSN=100%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305||
**********************************************************************
The first response C-1 has a status of Street name not found in
geography, which means that the street name exists but not in the specified
geography (Santa Clara instead of the correct Sunnyvale). The status message matches
the driven-by attribute for the StreetAddress state machine, so it returns to the
patternMatch state of the StreetAddress state machine (skipping many details
of the explanation because they are the same as example B, up to here).
This time when it processes the line:
the status does match ".*not found in geography". Therefore, this time it
goes to the adjacency01 state. The adjacency01 state has these control lines:
<Control name="ADJ">K10</Control>
<Control name="UGEOCODE_TACTIC">ADJACENCY SEARCH</Control>
It adds an adjacency (ADJ) keyword and changes the tactic name keyword; then it
sends query C-2. The response shows status “OK” because it found the address in the
neighboring city of Sunnyvale, so geocoding is successful and stops processing.
Example D: Badly misspelled city name
This example uses a good street address but a significantly misspelled city name:
610 grand fir ave, sunval, ca
report output:
**********************************************************************
** DDS QUERY D-1
** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand fir
4-50
October 15, 2010
**********************************************************************
**********************************************************************
** DDS RESPONSE D-1
** LADR|%EXTIME=78%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Geography not
found||
**********************************************************************
**********************************************************************
** DDS QUERY D-2
ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=GEOGRAPHY PATTERN
TERENCODING=iso-8859-1%Utrace2%LLMIN%LLMAX%G0%G1%G2%G4||
**********************************************************************
**********************************************************************
** DDS RESPONSE D-2
** LADR|%EXTIME=62%UGEOCODE_TACTIC=GEOGRAPHY PATTERN
MATCH%N=0%S=Geography not found%Utrace2=||
**********************************************************************
**********************************************************************
***
** DDS QUERY D-3
ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY
PATTERN
**********************************************************************
***
**********************************************************************
** DDS RESPONSE D-3
** LADR|%EXTIME=78%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY PATTERN
MATCH%N=1%S=OK%Utrace2=|%G0=USA%G1=CA%G2=SANTA
AVE%PSN=100%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305||
**********************************************************************
The first query D-1 fails with status Geography not found because the city
name is badly misspelled and doesn’t match. This time we see a case that we haven’t
yet seen: The status matches the driven-by attribute for the other state machine.
Therefore, the geocoder switches to the Geography state machine. Since the
Geography state machine has not yet been active, it doesn’t have a last state to return
4-51
to. It goes to the first state, which is placeSearch. Note that this is the first real
State, not the EntryPoint.
Normally, if Geography is entered at its EntryPoint, it is doing a geographic
lookup, not a street address lookup, and it uses an LGEO query token. However, since it
got here this time by a lateral transfer and doesn’t go through the EntryPoint, it
leaves the query token unchanged as LADR.
The placeSearch state sets quite a few input and control keywords, which we will
not examine closely because they are mostly very similar to previous examples.
However, a few are worth noting and some show features of the geocoder that
previous examples have not used. Consider these lines from placeSearch:
<Control name="Utrace2"/>
<Control name="G4" if-input-contains="G4|G5"/>
The Utrace2 line is a user-defined keyword. It is a leftover line used to trace which
states were used in debugging SimpleDemo, and you can ignore it.
However, the G4 line illustrates a very useful capability in its attribute if-inputcontains="G4|G5". This means “if input contains either G4 or G5.” The pipe
symbol ‘|’ means “or” in the context of values within quotation marks for attributes
such as if-input-contains, driven-by, or if-status.
Other logical operators that you can use in that context are a comma for “and” and ‘!’
for negation. For example, the WesternLocaleStateMachine’s EntryPoint has a
conditional if-input-contains=”SN,!XSN”. This means “if the input contains an
SN and does not contain an XSN.”
When placeSearch has set up all its inputs and controls, it sends the D-2 query. The
D-2 response shows status Geography not found, which is not surprising since
the inputs are the same and the required pattern match score for G4 (the misspelled
city name) is the same as in the D-1 query. A more sophisticated geocoder than
SimpleDemo would probably handle the situation in a more sophisticated way.
Since the status matches the driven-by attribute for Geography, the geocoder
comes back to the Geography state machine and comes back to the placeSearch
state where it was. The next line is this:
<NextState if-input-contains="G1|G2|G4|G5">
SimpleDemo.Geography.aggressivePlaceSearch</NextState>
</State>
This means that if the input contains any one of G1, G2, G4, or G5, go to state
aggressivePlaceSearch. Since the input contains both G1 and G4, the condition is
met and it changes state to aggressivePlaceSearch, which has the following
lines:
4-52
October 15, 2010
These lines relax the match quality scores required to get good matches for several
keywords. With these relaxed match requirements in query D-3, DDS finds a match
as shown in response D-3.
Note that the aggressivePlaceSearch state contains no NextState element and
there is no State after it in the Geography state machine. This means that if the D-3
query failed again with the same status, when the driven-by attribute brought it back
to the same state machine and the same state, it would have no further processing to
do, so geocoding would fail.
Example E: Misspelled street and city names
This example uses misspelled city name along with misspelled and incomplete street
name:
610 grand fur, sunval, ca
report output:
**********************************************************************
** DDS QUERY E-1
** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand
fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE E-1
** LADR|%EXTIME=62%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Geography not
found||
**********************************************************************
**********************************************************************
** DDS QUERY E-2
fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=GEOGRAPHY PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE E-2
** LADR|%EXTIME=47%UGEOCODE_TACTIC=GEOGRAPHY PATTERN
MATCH%N=0%S=Geography not found%Utrace2=||
**********************************************************************
**********************************************************************
** DDS QUERY E-3
fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY
4-53
PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE E-3
** LADR|%EXTIME=78%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY PATTERN
MATCH%N=0%S=Street name not found%Utrace2=||
**********************************************************************
**********************************************************************
** DDS QUERY E-4
fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME
PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE E-4
MATCH%N=2%S=OK%Utrace2=|%G0=USA%G1=CA%G2=SANTA
AVE%PSN=82%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305|%G0=USA%G1=CA%G2=SANTA
CLARA%G4=SUNNYVALE%G6=94087%PG=85%SN=LA GRANDE DR%PSN=71%VR=2,3733841,12203978,0,218%AR=698 - 608%LL=37.338409,-122.037760||
**********************************************************************
This example combines the kind of results that occurred in several previous examples,
to make a more complex case in which the state transitions go back and forth between
two state machines.
Queries E-1 and E-2 follow the same pattern as example D, getting Geography not
found status for the tactic PATTERN MATCH, switching to the Geography state
machine and getting the same status for tactic GEOGRAPHY PATTERN MATCH.
Query E-3 uses tactic AGGRESSIVE GEOGRAPHY PATTERN MATCH and gets a
geography match, but the street name doesn’t match, so the status is Street name
not found. This status and the driven-by attributes cause the geocoder to switch
back to the StreetAddress state machine. There it does the same process as
example B to find a street name match using the AGGRESSIVE STREETNAME
PATTERN MATCH tactic in query E-4.
4-54
October 15, 2010
Example F: Non-existent street name with good city name
This final example uses a completely wrong street name with a good city name:
610 bjkdslkdiufifej ave, sunnyvale, ca
report output:
**********************************************************************
** DDS QUERY F-1
** LADR|%G0=USA%G1=CA%G4=sunnyvale%SN=bjkdslkdiufifej
**********************************************************************
**********************************************************************
** DDS RESPONSE F-1
found||
**********************************************************************
**********************************************************************
** DDS QUERY F-2
** LADR|%G0=USA%G1=CA%G4=sunnyvale%SN=bjkdslkdiufifej
ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME
PATTERN
**********************************************************************
**********************************************************************
** DDS RESPONSE F-2
MATCH%N=0%S=Street name not found||
**********************************************************************
**********************************************************************
** DDS QUERY F-3
**
LGEO|%G0=USA%G1=CA%G4=sunnyvale%CUST=someclient|%UGEOCODE_TACTIC=GEOGR
APHY PATTERN
MATCH%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARACTERENCODING=iso8859-1%LL%LLMIN%LLMAX%CITYCENTER%G0%G1%G2%G4||
**********************************************************************
**********************************************************************
** DDS RESPONSE F-3
** LGEO|%EXTIME=406%UGEOCODE_TACTIC=GEOGRAPHY PATTERN
MATCH%N=1%S=OK|%G0=USA%LL=37.371560,122.038380%CITYCENTER=SUNNYVALE%G1=CA%G2=SANTA
4-55
CLARA%G4=SUNNYVALE%PG=100%LLMIN=37.254639,122.156982%LLMAX=37.433165,-121.923524||
**********************************************************************
This example begins the same way as example B, getting Street name not found
status in response F-1. But this time the AGGRESSIVE STREETNAME PATTERN
MATCH tactic also fails with the same status in response F-2. The NextState lines
for aggressivePatternMatch are these:
<NextState>SimpleDemo.StreetAddress.removeStreetLevelInfo</NextState>
This time, the if-status doesn’t match, so it doesn’t try adjacency. Instead, it falls
through to the NextState unconditional transfer to the removeStreetLevelInfo
state, a state that we have not yet seen in any examples. This state also illustrates some
capabilities that we have not yet seen. This state is as follows:
<State name="removeStreetLevelInfo" execute-query="false">
<Remove>
<Input name="SN"/>
<Input name="NO"/>
<Control name="SN"/>
<Control name="QSN"/>
<Control name="VR"/>
</Remove>
<NextState query-token="LGEO">SimpleDemo.Geography.$RESUME_STATE</
NextState>
</State>
The removeStreetLevelInfo state gives up on finding the street address and tries
to simply find the geography (in this case, the city Sunnyvale). The Remove element
removes all the specified input and control keywords from the DDS query. These are
the street address keywords. In the F-3 query, you can see that these keywords are no
longer present. The NextState element changes the query token from LADR to LGEO
because it is no longer trying to find a street address. In this state, the end of inputs and
controls and the arrival at a NextState element does not result in sending a new DDS
query because of the execute-query="false" attribute in the State line.
It then does a direct transfer to the Geography state machine’s current state
$RESUME_STATE. That means the last state that was active in that state machine. In
this case, no state has yet been active in Geography, so it goes to the first state,
placeSearch. The LGEO query F-3 now easily finds Sunnyvale.
4-56
October 15, 2010
4.5 Presentation Service (Drawing
Maps)
Presentation Service requests and responses are all identical to the standard high level
Requests and Responses” on page 4-4.
Figure 4.9. The Request/Response Elements of Presentation Service
Map01.xml example request
Map01.xml example response
<ns1:Request methodName="PortrayMapRequest" requestID="10"
<ns1:PortrayMapRequest>
<ns1:Output height="400" width="400">
<ns1:CenterContext SRS="WGS-84">
<ns1:CenterPoint>
<ns2:pos xmlns:ns2="http://www.opengis.net/gml">41.002 72.002</ns2:pos>
</ns1:CenterPoint>
<ns1:Radius unit="KM">0.3</ns1:Radius>
</ns1:CenterContext>
</ns1:Output>
</ns1:PortrayMapRequest>
</ns1:Request>
<ns1:PortrayMapResponse>
<ns1:Map>
<ns1:Content height="400" format="GIF" width="400">
<ns1:URL>http://ws.decarta.com:8080/openls/image/
1903147324.gif</ns1:URL>
</ns1:Content>
<ns1:CenterPoint>
</ns1:CenterPoint>
</ns1:Map>
</ns1:PortrayMapResponse>
</ns1:Response>
4.5.1 Requests
shown in the example Presentation Service request.
4.5.1.1 methodName
The value of methodName is PortrayMapRequest in requests to draw a map.
4-57
October 15, 2010
Presentation Service (Drawing Maps)
4.5.1.2 PortrayMapRequest
The PortrayMapRequest element typically includes elements which specify the
size of the generated map, the center point of the map, and the size of the area covered
by the map. Using the attribute Azimuth, you can even rotate the image based on the
angle in degrees (0 to 360).
In versions greater that 4.4.1, when using TileGrid, the PortrayMapRequest
element must contain the rel attribute.
4.5.2 Responses
shown in the example Presentation Service response.
4.5.2.1 PortrayMapResponse
The main element of a PortrayMapResponse element is the Map element.
4.5.2.1.1 Map
The Map element can return either a URL of the generated map’s file location or a
binary stream of the map data.
URL
A URL element specifies the URL of the generated graphic file for the map.
deCarta provides a number of proprietary extensions to the OpenLS specification
which make it easier to create an application. In particular, several extensions make it
easier to create an application with many of the familiar features that users expect
from a mapping application.
Note: Most of the maps in this section have been reduced in size; therefore, the labels
may not be as legible as they are on the normal size maps.
4-58
October 15, 2010
4.5.3.1 CenterAddress
The CenterAddress extension enables an application to request that a geocoded
address be the center point of a generated map. The application does not have to do a
separate geocoding step and then use the determined location in a request to create a
map. You simply use the CenterAddress feature to specify the center point of the
map as an address. The response returns the geocoded location so that you have it if
you want to use it in the future; for example, you might use the location to put a
marker on future maps to show the location that the user originally specified, when
they pan or zoom around on the map.
The radius in the CenterAddress is optional. If omitted, the server picks a radius
that provides an appropriate “autoscaled” value. For example, if the address is “4 n
2nd st, 95113" the radius assigned by the server will be smaller than if the address was
“san jose CA”.
4-59
October 15, 2010
CenterAddress is an element of the Output element of PortrayMapRequest.
Here is an example of its usage in a request:
Figure 4.10. CenterAddress In PortrayMapRequest
Request
Response
xls">
<ns1:RequestHeader clientPassword="XXX" configuration="blue-steel"
sessionID="999" clientName="XXX"/>
<ns1:Request requestID="10" methodName="PortrayMapRequest"
<ns1:Output width="500" height="500">
<ns1:CenterAddress>
<ns1:Radius unit="KM">1</ns1:Radius>
<ns1:Address countryCode="US" language="EN">
<ns1:freeFormAddress>1760 halford ave., santa clara, ca</
ns1:freeFormAddress>
</ns1:Address>
</ns1:CenterAddress>
</ns1:Output>
<ns1:Overlay>
<ns1:Style>
<ns1:StyleContent>red-dot.gif:,Font3,TL</ns1:StyleContent>
</ns1:Style>
</ns1:Overlay>
</ns1:Request>
</ns1:XLS>
<ns1:Map>
<ns1:URL>http://ws.decarta.com:8080/openls/image/2124343908.gif</ns1:URL>
</ns1:Content>
<ns1:CenterPoint>
<ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131
-121.9981</ns2:pos>
</ns1:CenterPoint>
</ns1:Map>
<ns1:GeocodeResponseList numberOfGeocodedAddresses="1">
<ns3:pos>37.355131 -121.9981</ns3:pos>
</ns3:Point>
<ns1:freeFormAddress>1760 HALFORD AVE, SANTA
CLARA, CA 95051</ns1:freeFormAddress>
</ns1:Address>
accuracy="1.0"/>
</ns1:GeocodeResponseList>
</ns1:Response>
</ns1:XLS>
The CenterAddress element of the request is highlighted in bold. Note that the
request also uses an Overlay element to request the “red dot” overlay at the geocoded
address. Using the CenterAddress element in the request causes the response to
include a GeocodeResponseList, which is highlighted in the response. The
GeocodeResponseList element is a standard OpenLS feature for geocoding
responses, but this usage in the PortrayMapResponse is a deCarta extension.
4-60
October 15, 2010
Here is the map generated by that request:
Figure 4.11. Map Created With CenterAddress Feature
The maps in the next several sections work sequentially from this original map.
4.5.3.2 Pan
The pan feature enables you to pan in any of eight directions to create a new map with
a shifted center point. This feature directly enables a simple interface to perform the
familiar task of web mapping applications, to pan north, northeast, east, southeast, and
so on. You do not have to calculate the map’s new center point; DDS Web Services
does that for you, based on the previous map’s center point and the panning direction.
You can also pan to a specified lat/lon which is useful when using TileGrid.
pan is an attribute of the PortrayMapRequest element, which looks like this:
<ns1:PortrayMapRequest pan="E">
For the pan values N, S,E, W, NE, SE, SW, and NW, it pans a half screen so that the point
that was at the center of the previous map appears at the edge of the map.
For the pan values toLat and toLon these are the lat/lons you pan to using the pan
offsets (numTiles) inside the pan elements. For example:
<ns1:Pan direction="E" numTiles="0.30859375" toLon="-121.8899"/>
4-61
October 15, 2010
<ns1:Pan direction="N" numTiles="0.05078125" toLat="37.337359"/>
You can use these two Pan elements in both DECARTA and GLOBEXPLORER tile grids.
Given the map in Figure 4.11, which was created by the request in Figure 4.10, you
can now use the following request to pan eastward half the map’s width:
Figure 4.12. Request To Pan Eastward
Request
Response
<ns1:PortrayMapRequest pan="E">
<ns1:CenterPoint>
-121.9981</ns2:pos>
</ns1:CenterPoint>
</ns1:Output>
<ns1:Overlay>
<ns1:Position>
<ns3:pos>37.355131 -121.9981</ns3:pos>
</ns3:Point>
</ns1:Position>
<ns1:Style>
<ns1:Name>red-dot.gif</ns1:Name>
</ns1:Style>
</ns1:Overlay>
<ns1:Map>
</ns1:Content>
<ns1:CenterPoint>
-121.98677858467161</ns2:pos>
</ns1:CenterPoint>
<ns1:Radius unit="KM">1.000000000000153snip</ns1:Radius>
</ns1:Map>
This code shows only the PortrayMapRequest element, because the request header
and other higher level parts of the request do not change. Notice that the request
specifies the same latitude and longitude as the center of the map in Figure 4.11. This
illustrates that DDS Web Services calculates the new map center for you, and it returns
the new center in the response’s pos element of CenterPoint (highlighted). If you
then want to do more panning or zooming, you will use this new center point in the
request, and again you will not have to calculate the subsequent center point.
4-62
October 15, 2010
This request generates the following map, with the center shifted eastward half the
width of the map:
Figure 4.13. Map After Panning Eastward
Notice that the “red-dot” icon, which shows the spot of the previously geocoded
address is now exactly at the left edge of the map. If you look at the Overlay element
in this request, you will notice that it now has to specify the location (latitude and
longitude) of the overlay because the geocoding to find that position is not happening
in this query. The application saved that information from the previous response in
order to build this Overlay element.
If you continue to pan and zoom from this map, your requests should continue to
include this Overlay element to mark that location. If your panning and zooming
causes that location to be outside the map’s area, no harm is done; it just drops out.
But when panning and zooming brings it back into the field of view, the carried over
Overlay element causes the icon to re-appear in its proper location.
4.5.3.3 Zoom
The zoom feature also makes it easy to use a familiar feature of mapping applications,
to zoom in or out, keeping the map center the same. When you use Zoom, DDS Web
Services calculates the new map radius for you.
4-63
October 15, 2010
Like pan, zoom is an attribute of the PortrayMapRequest element. Here is an
example:
Positive values mean to zoom out; negative values mean to zoom in. The magnitude of
the value is the fractional amount to change the map’s covered area’s width. The
change is based on the equation new_radius = old_radius X (1 +
zoom_value). The values for zoom must therefore be greater than -1 because any value
less than -1 would ask the map area to shrink to less than nothing.
This example continues from the map in Figure 4.13, created by the request in
Figure 4.12.
Figure 4.14. Request To Zoom Out 40%
Request
Response
<ns1:CenterPoint>
-121.98677858467161</ns2:pos>
</ns1:CenterPoint>
<ns1:Radius unit="KM">1.0000000000001534328snip5</
ns1:Radius>
</ns1:Output>
<ns1:Overlay>
<ns1:Position>
<ns3:pos>37.355131 -121.9981</ns3:pos>
</ns3:Point>
</ns1:Position>
<ns1:Style>
</ns1:Style>
</ns1:Overlay>
<ns1:Map>
</ns1:Content>
<ns1:CenterPoint>
-121.98677858467161</ns2:pos>
</ns1:CenterPoint>
<ns1:Radius unit="KM">1.400000005960484683598snip</
ns1:Radius>
</ns1:Map>
Notice that the request keeps the same position (latitude, longitude) and radius that
were returned in the previous response. The response again returns the center position
and the new radius. Notice also that the request continues to include the same
Overlay element; if that position is within the map’s area, it will appear; otherwise, it
is ignored.
4-64
October 15, 2010
Figure 4.15 shows the resulting new map, showing that the original geocoded position
is now still within the map’s area:
Figure 4.15. Map After Zooming Out
4.5.3.4 Re-center Map (Screen Coordinates on Click)
Another familiar feature of mapping applications is to re-center the map at a location
clicked by the user. deCarta’s ScreenCoordinate extension makes that feature easy
to implement.
The ScreenCoordinate extension is an element of the PortrayMapRequest
element. It appears in context as follows:
<ns1:ScreenCoordinate y="438" x="177"/>
...>
</ns1:Output>
...
The y and x values are the number of pixels from the upper left corner of the map to
the spot where the user clicked.
4-65
October 15, 2010
This example continues from the map in Figure 4.15, created by the request in
Figure 4.14. The user clicks within Homestead Park, near the bottom of the map in
Figure 4.15:
Figure 4.16. Request To Re-center Map Using ScreenCoordinate
Request
Response
<ns1:ScreenCoordinate y="438" x="177"/>
<ns1:CenterPoint>
</ns1:CenterPoint>
<ns1:Radius
unit="KM">1.400000005960484683598110677849035710096359252929687
5</ns1:Radius>
</ns1:Output>
<ns1:Overlay>
<ns1:Position>
<ns3:pos>37.355131 -121.9981</ns3:pos>
</ns3:Point>
</ns1:Position>
<ns1:Style>
</ns1:Style>
</ns1:Overlay>
<ns1:Map>
</ns1:Content>
<ns1:CenterPoint>
<ns2:pos xmlns:ns2="http://www.opengis.net/
gml">37.34565655823944 -121.99140677920954</ns2:pos>
</ns1:CenterPoint>
<ns1:Radius
unit="KM">1.400088354824344794025137161952443420886993408203125
</ns1:Radius>
</ns1:Map>
As in the previous examples, the application’s request includes the old latitude and
longitude; DDS Web Services calculates the new center point from the
ScreenCoordinate element, the old center point, and the map scale; and the
response returns the new center location. The example request continues to include the
Overlay element.
4-66
October 15, 2010
Figure 4.17 shows the new map, with Homestead Park in the center:
Figure 4.17. Map After Re-centering, Using ScreenCoordinate
4.5.3.5 Shape
The Shape feature enables you to overlay points, lines, and polygons from a custom
dataset on top of the map display. When you use Shape in a PortrayMapRequest,
you can control the type of shape to draw (circle, rectangle, polygon, or line), the
color, style, and width of the line, and its opacity.
The Presentation Service schema PresentationService.xsd contains the details
of the syntax for Shape. Please refer to information on the SHAPE keyword in the
Drill Down Server Reference Manual for additional details.
For an example of a map with a shape overlay, refer to the sample Map14.xml.
4-67
October 15, 2010
Figure 4.18. Shape In PortrayMapRequest
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <ns1:XLS ns1:lang="en" version="1.0" xmlns:ns1="http://www.opengis.net/
xls">
<ns1:RequestHeader configuration="stickville" clientPassword="abc123"
clientName="someclient" sessionID="999" />
- <ns1:Request methodName="PortrayMapRequest" requestID="10"
- <ns1:PortrayMapRequest fitOverlays="true">
- <ns1:Output width="400" height="400">
- <ns1:CenterContext SRS="WGS-84">
- <ns1:CenterPoint>
<ns2:pos xmlns:ns2="http://www.opengis.net/gml">41.002 -72.002</
ns2:pos>
</ns1:CenterPoint>
</ns1:Output>
- <ns1:Overlay>
<ns1:Shape type="CIRCLE" opacity="20" color="green" pointspec="LL"
radius="M100">41.003,-72.003</ns1:Shape>
</ns1:Overlay>
- <ns1:Overlay>
<ns1:Shape color="red" pointspec="LLs">2,41.003,-72.003,41.003,72.001</ns1:Shape>
</ns1:Overlay>
</ns1:Request>
</ns1:XLS>
When using the Stickville dataset, Map14.xml produces the display Figure 4.19:
4-68
October 15, 2010
Figure 4.19. Map Using Shape
4.5.3.6 Fit Overlays
The fitOverlays feature enables you to force the map’s extent to include all
specified Overlay elements in the generated map. Normally, if an Overlay element
lies outside the specified area for the map, then that overlay is simply ignored.
However, if you specify fitOverlays="true", then the map area will change to
include all overlays in the map. fitOverlays is not supported for tiling or draggable
maps.
The fitOverlays feature is an attribute of the PortrayMapRequest element. It
appears as follows:
<ns1:PortrayMapRequest fitOverlays="true">
Here is an example of a map request that specifies an overlay which is outside the
specified map area, so the overlay does not appear on the map. The overlay is the same
one that the previous examples have been using, but the latitude and longitude have
4-69
October 15, 2010
been rounded off to fewer digits. This map also uses a different map configuration file,
so the appearance is different. Here is the request and the resulting map:
Figure 4.20. Request For a Map With Overlay Outside the Map Area
Request
<ns1:CenterPoint>
-121.99140677920954</ns2:pos>
</ns1:CenterPoint>
</ns1:Output>
<ns1:Overlay>
<ns1:Position>
<ns3:pos>37.355131 -121.9981</ns3:pos>
</ns3:Point>
</ns1:Position>
<ns1:Style>
</ns1:Style>
</ns1:Overlay>
Figure 4.21. Map With an Overlay Outside the Map Area (i.e., Not Shown)
Here is the same request with nothing changed except to add a fitOverlays
attribute to the PortrayMapRequest element. Notice that the map area is expanded
4-70
October 15, 2010
to include the overlay and that the response reports the adjusted center position and
radius.
Figure 4.22. Map Using “fitOverlays” Option. Overlay Is Outside Specified Map Area
Request
Response
<ns1:PortrayMapRequest fitOverlays="true">
<ns1:CenterPoint>
gml">37.34565655823944 -121.99140677920954</ns2:pos>
</ns1:CenterPoint>
</ns1:Output>
<ns1:Overlay>
<ns1:Position>
<ns3:pos>37.355131 -121.9981</ns3:pos>
</ns3:Point>
</ns1:Position>
<ns1:Style>
</ns1:Style>
</ns1:Overlay>
<ns1:Map>
<ns1:URL>http://ws.decarta.com:8080/openls/image/1111643085.gif</
ns1:URL>
</ns1:Content>
<ns1:CenterPoint>
gml">37.34904388711108 -121.9930553916076</ns2:pos>
</ns1:CenterPoint>
<ns1:Radius unit="KM">1.0124935432863snip</ns1:Radius>
</ns1:Map>
Figure 4.23. fitOverlays Forces the Map Area to Include the Overlay
If you look closely, you’ll notice that the map does not simply zoom out until the
overlay is included. Rather, the map area extends in the required direction(s) until the
4-71
October 15, 2010
overlay is included. Also, it includes a little extra space so that the overlay is not at the
exact edge of the map.
4.5.3.7 Graphic Format Parameters
Several elements are available to specify various parameters that determine the quality
and type of output for certain graphical format outputs. These elements include jpgparameters, png-parameters, svg-parameters, and bmp-parameters. These
elements can specify such variables as JPG quality, JPG subsampling type, PNG
compression, SVG compression, and so on.
The line <ns1:jpg-parameters quality="80" subsampling="2x2"/> in
Figure 4.24 from the example file Map12.xml shows a map request that specifies the
JPG parameter quality. The presentation service schema
PresentationService.xsd also provides additional details.
Figure 4.24. Map Request Using Image Quality and Compression Level Parameters
Request
<ns1:Output format="JPG" height="400" width="400">
<ns1:CenterAddress>
<ns1:freeFormAddress>300 Second Ave, 11111</ns1:freeFormAddress>
</ns1:Address>
</ns1:CenterAddress>
<ns1:jpg-parameters quality="80" subsampling="2x2"/>
</ns1:Output>
4.5.3.8 GridLayer and TileGrid
TileGrid and GridLayer are deCarta extensions to enable draggable maps and
hybrid maps which overlay a map on aerial or satellite images of the area. Refer to the
Presentation Service schema PresentationService.xsd for details of the syntax.
For examples of draggable maps, refer to the samples Map09.xml and Map10.xml.
For an example of a hybrid map using GlobeXplorer imagery, refer to the sample
Map13.xml.
4.5.3.9 fixedgrid
The fixedgrid feature enables you to fix the URL for a given tile at a given zoom
level to always be the same by specifying fitOverlays="true".
4-72
October 15, 2010
The fixedgrid feature is an attribute of the PortrayMapRequest element. It
appears as follows:
<ns1:PortrayMapRequest fixedgrid="true">
Here is an example of a map request that specifies using fixed grid tile support:
Figure 4.25. Request For a Map Using Fixed Grid Tile
Request
<xls:PortrayMapRequest>
<xls:Output width="256" height="256" fixedgrid="true" useCache="true"
format="GIF" content="URL">
<xls:CenterContext SRS="WGS-84">
<xls:CenterPoint>
<gml:pos>41.002 -72.002</gml:pos>
</xls:CenterPoint>
<xls:Radius unit="KM">200</xls:Radius>
</xls:CenterContext>
<xls:TileGrid rows="4" columns="4">
<xls:GridLayer name="deCarta"/>
<xls:GridLayer name="globexplorer" meta-inf="zoom=17"/
>
<xls:Pan direction="N" numTiles="0"/>
<xls:Pan direction="S" numTiles="0"/>
<xls:Pan direction="E" numTiles="0"/>
<xls:Pan direction="W" numTiles="0"/>
>
</xls:TileGrid>
</xls:Output>
</xls:PortrayMapRequest>
</xls:Request>
</xls:XLS>
4-73
October 15, 2010
Route Service (Calculate Routes)
4.6 Route Service (Calculate
Routes)
Route Service requests and responses are all identical to the standard high level
Figure 4.26. The Request/Response Elements of Route Service
Route01.xml example request
Route01.xml example response
<ns1:Request methodName="DetermineRouteRequest" requestID="10"
<ns1:DetermineRouteRequest provideRouteHandle="false">
<ns1:RoutePlan>
<ns1:RoutePreference>Fastest</ns1:RoutePreference>
<ns1:WayPointList>
<ns1:StartPoint>
<ns1:freeFormAddress>1 First St., Stickville, NY 11111</
</ns1:Address>
</ns1:StartPoint>
<ns1:EndPoint>
<ns1:freeFormAddress>399 3rd ave, Stickville, NY 11111</
</ns1:Address>
</ns1:EndPoint>
</ns1:WayPointList>
</ns1:RoutePlan>
<ns1:RouteInstructionsRequest/>
</ns1:DetermineRouteRequest>
</ns1:Request>
<ns1:DetermineRouteResponse>
<ns1:StartAddressCandidates numberOfGeocodedAddresses="1">
<ns2:pos>41.003901 -72.003</ns2:pos>
</ns2:Point>
<ns1:freeFormAddress>1 1st St, NEW YORK, NY 11111</
</ns1:Address>
accuracy="1.0"/>
</ns1:StartAddressCandidates>
<ns1:EndAddressCandidates numberOfGeocodedAddresses="1">
...
</ns1:EndAddressCandidates>
<ns1:RouteSummary>
<ns1:TotalTime>P0DT0H1M21S</ns1:TotalTime>
<ns1:TotalDistance uom="MI" value="0.3512"/>
<ns1:BoundingBox>
<ns4:pos xmlns:ns4="http://www.opengis.net/gml">41.001 -72.003</
ns4:pos>
</ns1:BoundingBox>
</ns1:RouteSummary>
<ns1:RouteInstructionsList ns1:lang="english">
<ns1:RouteInstruction description="route maneuver 1"
duration="P0DT0H0M46S">
<ns1:Instruction>Proceed along 1st St for 0.2MI. Turn left on 3rd
Ave.</ns1:Instruction>
<ns1:distance uom="MI" value="0.2004"/>
</ns1:RouteInstruction>
<ns1:RouteInstruction description="route maneuver 2"
...
</ns1:RouteInstructionsList>
</ns1:DetermineRouteResponse>
</ns1:Response>
4-74
October 15, 2010
4.6.1 Requests
shown in the example Route Service request.
To support logistics in routing, DDS logistics-based keywords are available in W.S.
Note that these DDS keywords are available only through the DDS “logistics”
package, which contains a specialized DDS Route Plug-in.
4.6.1.1 methodName
The value of methodName is DetermineRouteRequest for a route service request.
4.6.1.2 DetermineRouteRequest
The DetermineRouteRequest element includes all the main parts of a specific
routing request. Routes and driving directions can be produced using either DDS
Routing Plug-in’s RMAN query or RTXT query. To use the RMAN-based system, you
have to explicitly ask for it in DetermineRouteRequest using routeQueryType.
DetermineRouteRequest includes nested elements such as RoutePlan (specifies
type of route, origin, destination, and so on), RouteInstructionsRequest (asks
for detailed maneuver instructions) if applicable, and AlternateRoute, a deCarta
extension which requests alternate routes be returned.
4.6.1.2.1 routeQueryType
The routeQueryType selects the DDS Routing Plug-in query to be used in
determining the route. When routeQueryType=RMAN the DDS query RMAN is used.
When no routeQueryType is specified, the default DDS query RTXT is used. Refer
to the sample Route10.xml for more information.
4.6.1.2.2 RoutePlan
The RoutePlan element provides the information necessary to calculate the route,
such as the type of route (fastest, shortest, pedestrian), the start and end points, turn
regulation (prefer left turns and/or allow almost no U-turns), the departure and arrival
angles, and vehicle types for more vehicle-specific routing. Departure and arrival
angles information may then be used in subsequent rerouting calculations.
RoutePlan does not specify how to report the found route, such as whether to include
overview and maneuver maps and whether to include detailed turn-by-turn
instructions. Other elements request those kinds of information.
4-75
October 15, 2010
RoutePreference
The RoutePreference specifies the kind of route to find. The possibilities currently
are the following: fastest, shortest, pedestrian, AvoidFreeways,
NoFreeways, MoreFreeways, IgnorePipes, easy, and addAvoidArea.
WayPointList
The WayPointList specifies the route’s starting point (StartPoint) and ending
point (EndPoint). For multiple waypoint routing, use ViaPoint. The deCarta
freeFormAddress extension allows you to specify these points by using addresses
rather than latitude-longitude, to save you a separate geocoding step for each
waypoint.
For an example of multiple waypoint routing, refer to the sample Route07.xml.
4.6.1.2.3 distanceUnit
The distanceUnit element specifies the unit used for the distance returned in the
response. The default value is MI (miles). distanceUnit supports all units of
measure that OpenLS supports.
4.6.1.2.4 RouteInstructionsRequest
The RouteInstructionsRequest element requests detailed turn-by-turn
instructions for the route. It results in a RouteInstructionsList element in the
response.
Route instructions generated from maneuver rules other than the default can be
returned by specifying the maneuver rules file to use. To generate route instructions in
French, add the following:
<ns1:RouteInstructionsRequest rules="maneuver-rules-FR" /
>
The “rules” attribute may also be used to specify an XML-based set of rules for use
with RMAN. Maneuver-rules.xml is a server-side XML-based rules file residing in
the OpenLS application under WEB-INF/classes/com/telcontar/openls/
server/route/rules.
For more information detail on maneuver rules files, refer to “Rules for Maneuver
Generation” on page 4-83.
4-76
October 15, 2010
4.6.1.2.5 RouteGeometryRequest
The RouteGeometryRequest element requests a RouteGeometry element in the
response, which provides a list of points for the route, which provide the complete
geometry of the route. When returnRouteIDOnly is set to TRUE, a Base64-encoded
route ID is returned. Route ID is a a shortened form of a calculated route that
completely identifies the full route.
4.6.1.2.6 RouteMapRequest
The RouteMapRequest element requests maps of the route. It can request an
overview map of the entire route and maps of individual maneuvers of the route. Maps
are returned in RouteMap elements in the response. See “RouteMapRequest Style” on
page 4-80 for more information about this element, examples of its usage, and
information about deCarta’s proprietary extensions.
4.6.1.2.7 RouteGeometryFormat
The routeGeometryFormat element specifies the format of response. Set to “VR”,
VRs are returned as a list in the element VectorString. When set to
“LineString”, line strings are returned. LineString is the default.
4.6.2 Responses
shown in the example Route Service response.
4.6.2.1 DetermineRouteResponse
Analogous to the DetermineRouteRequest, the DetermineRouteResponse
element includes all the main body of a routing response.
4.6.2.1.1 StartAddressCandidates and EndAddressCandidates
These deCarta extensions to the OpenLS specification return information about the
candidate points that were chosen for origin and destination, for example, by
geocoding freeFormAddress elements for those points. For examples and details,
see “StartAddressCandidates, EndAddressCandidates” on page 4-79.
4-77
October 15, 2010
4.6.2.1.2 RouteSummary
The RouteSummary element provides general information about the calculated route
such as the total expected time, the total distance, and a bounding box that includes the
entire route.
4.6.2.1.3 RouteInstructionsList
The RouteInstructionsList provides turn-by-turn directions that are generated
by the Drill Down Server. A sequence of RouteInstruction elements comprise the
RouteInstructionList element. Each RouteInstruction element includes a
description attribute such as route maneuver 2; you can use these
description attributes to correlate maneuver instructions with maneuver maps that
are part of the RouteMap element. The RouteMap element also has a description
attribute which has values such as route maneuver 2.
4.6.2.1.4 RouteGeometry
The RouteGeometry element provides a sequence of points that form the geometry
of the entire route. These points include both maneuver points and points that simply
reflect the geometry of the roads that are followed in the route.
4.6.2.1.5 RouteID
The RouteID element provides a deCarta proprietary Base64 encoded Route ID. An
application can pass this RouteID back to the server in a PortrayMapRequest
<Overlay> element, in order for the route to be rendered on top of tiles. This is more
efficient than passing the result of the RouteGeometry element, which is XML
vectors of long distance routes.
4.6.2.1.6 RouteMap
Each RouteMap element provides a map of either an overview of the entire map or of
an individual maneuver. The description attribute tells whether it is an overview or
which specific maneuver. The map can be returned in various graphical formats and as
either a data stream or a URL of the map stored on the server. See “RouteMapRequest
Style” on page 4-80 for more information and detailed examples of using overview
and maneuver maps.
4-78
October 15, 2010
Several deCarta extensions to the Route Service schema make it easier to develop an
application. Some of these extensions have been adopted for the OpenLS 1.1 and 2.0
specifications.
4.6.3.1 StartAddressCandidates, EndAddressCandidates
The features StartAddressCandidates and EndAddressCandidates are
elements of the DetermineRouteResponse element. They return a list of
GeocodedAddress elements which closely match the input address for the origin
and destination of a route. They are useful for dealing with ambiguous input or
common spelling errors. These features make it easy to present to a user a list of
potential matches when multiple geocoded addresses closely match the user’s input,
so that the user can verify that the correct one was chosen or can select the correct one
from a list.
Here is an example from the ClientWebApp sample application that shows how you
can use these features. The screen capture in Figure 4.27 shows the user’s input
starting address “4 2nd st., san jose, ca” which is an ambiguous address because there
can be both a 4 N. 2nd St. and a 4 S. 2nd St. in San Jose. The application uses one
matching address to calculate the route but offers the user the option to specify that the
other address was the correct one. (In fact, even if the user had entered “4 N. 2nd St.”
this application would offer the S. 2nd St. option because it is still a close match.)
Figure 4.27. ClientWebApp Geocodes an Ambiguous Address
Here is the part of the request which specifies the starting point for the route, based on
the user’s input and the part of the response which uses the
4-79
October 15, 2010
StartAddressCandidates element to report the multiple possible geocoded
addresses:
Figure 4.28. StartAddressCandidates Reports Multiple Matching Origin Addresses
Request
Response
<ns1:StartPoint>
<ns1:Address countryCode="US" language="EN">
<ns1:freeFormAddress>4 2nd st., san jose, ca
</ns1:freeFormAddress>
</ns1:Address>
</ns1:StartPoint>
<ns1:StartAddressCandidates numberOfGeocodedAddresses="2">
<ns2:pos>37.336776 -121.889585</ns2:pos>
</ns2:Point>
<ns1:freeFormAddress>4 N 2ND ST, SAN JOSE, CA 95113</
</ns1:Address>
accuracy="0.93"/>
<ns3:pos>37.336559 -121.889426</ns3:pos>
</ns3:Point>
<ns1:freeFormAddress>4 S 2ND ST, SAN JOSE, CA 95113</
</ns1:Address>
accuracy="0.93"/>
</ns1:StartAddressCandidates>
4.6.3.2 RouteMapRequest Style
The style attribute of the RouteMapRequest element enables you to request
different sizes of maps for the route overview and for the maneuvers along the route.
Maneuver maps are oriented so that “up” on the map is the direction of travel along
the segment leading to the maneuver point. The sample XML request Route05.xml
demonstrates this capability. Here is the request with the relevant part highlighted,
4-80
October 15, 2010
along with selected parts of the response (because the response is too long to fit
entirely), followed by the route overview map and the smaller maneuver maps:
Figure 4.29. RouteMapRequest Asks for Different Size Overview and Maneuver Maps
Request
Response
<ns1:RoutePlan>
<ns1:WayPointList>
<ns1:StartPoint>
<ns1:freeFormAddress>1 First St., Stickville, NY 11111</
</ns1:Address>
</ns1:StartPoint>
<ns1:EndPoint>
<ns1:freeFormAddress>399 3rd ave, Stickville, NY 11111</
</ns1:Address>
</ns1:EndPoint>
</ns1:WayPointList>
</ns1:RoutePlan>
<ns1:RouteGeometryRequest/>
<ns1:RouteMapRequest>
<ns1:Output style="Overview" width="500" height="500"/>
<ns1:Output style="Maneuver" width="200" height="200"/>
</ns1:RouteMapRequest>
<ns1:RouteMap description="Route Overview">
ns1:URL>
</ns1:Content>
...
</ns1:RouteMap>
<ns1:RouteMap description="route maneuver 1">
ns1:URL>
</ns1:Content>
...
</ns1:RouteMap>
<ns1:RouteMap description="route maneuver 2">
ns1:URL>
</ns1:Content>
...
</ns1:RouteMap>
4-81
October 15, 2010
Figure 4.30. Different Size Route Overview and Maneuver Maps
Maneuver 1 map
Maneuver 2 map
Route overview map
4.6.3.3 RouteInstruction Description
The description attribute of the RouteInstruction element was a deCarta
extension but it has been adopted for inclusion in the OpenLS specification version
1.1. The description attribute gives a description for each maneuver, such as
route maneuver 3. The RouteInstruction element also includes such
information as the distance of the maneuver, the expected travel time, and a plainlanguage description of the maneuver. Almost all the sample XML requests for the
routing service get responses which illustrate the RouteInstruction element.
4.6.3.4 Route Finding Preferences
You can specify various kinds of route searches such as fastest, shortest, or pedestrian
routes. You can also specify to avoid certain types of roads such as highways limited
access) or tollways if possible.
To request that the route avoid highways or tollways, use the element AvoidFeature,
which has the possible values Highway and Tollway.
4-82
October 15, 2010
To request a specific kind of route calculation, use the element RoutePreference,
which has possible values such as Fastest, Shortest, and Pedestrian. These
routing types correspond to routing types provided by the DDS, and you can find
details about them in the Drill Down Server Reference Manual.
4.6.3.4.1 AlternateRoute
Using the AlternateRoute element, you can specify in a route request, that
alternate routes be returned in addition to the requested route. For example, to
generate one alternate route in addition to the requested route, add the following:
<attribute name="numAltRoutes" type="int" use="optional"
default="1">
As defined in the request, the AlternateRoute element returns the number of
alternate routes returned in addition to the requested route.
<element name="AlternateRoute"
type="xls:DetermineRouteResponseType" minOccurs="0"
maxOccurs="unbounded">
4.6.4 Rules for Maneuver Generation
The route finding algorithm uses a “maneuver rules” files to determine how to identify
which actions constitute a maneuver and to determine how to describe the maneuver.
When the default routeQueryType (RTXT) is used, the following maneuver rules
files found in the Drill Down Server/rules folder are used:
• maneuver-rules.xml which is the standard default file; it generates driving
instructions in U.S./English.
• maneuver-rules-FR.xml which generates driving instructions in French.
You can edit those files and create additional rules files. To use a rules file other than
the default in a request, you specify the optional attribute rules for a
RouteInstructionsRequest element. For detailed information about RTXT-based
maneuver rules files, refer to the Drill Down Server Reference Manual.
There are two types of XML-based sets of rulesof maneuvers for use in generating
routes based on the DDS RMAN query. For generating vehicle instructions, use files of
type “manuever-rules-two-character lang code.xml”. For generating pedestrian
instruction, use files of type “manuever-rules-pedestrian-two-character lang
code.xml“.
4-83
October 15, 2010
When the routeQueryType is set to RMAN, use these types of files located in /
server/Tomcat6.0.18/webapps/openls/WEB-INF/classes/com/
telcontar/openls/server/route/rules.
The software distribution includes two maneuver rules files that are customized to
improve routing instructions for use with specific vendors’ data for North America.
The files for Tele Atlas and NAVTEQ data respectively are the following:
• maneuver-rules-TA-2007-2-NAM.xml
• maneuver-rules-NT-2007-1-NAM.xml.
4.6.4.1 RMAN-Based Routing
RMAN-based routing allows more localization (supports non-English sentence
construction) and finer control over driving directions through reducing redundant
instructions than the RTXT-based default routing. Routes that use the RMAN routing will
be handled more efficiently. RMAN-based maneuver rules are used to produce the text
of driving directions. Unlike RTXT rules, RMAN rules are not based on specifying the
geometry of intersections. Most output keywords for RMAN may be used to generate
Web Services based driving directions maneuvers. For more information on DDS
RMAN output keywords available in DDS Web Services RMAN-based routing
“${variable}” on page 4-86.
You can use RMAN-based routing in two ways. The first way is to use DDS rather than
Web Services to generate RMAN maneuver instructions by setting the
UseRMANInDDS=TRUE in the web.xml file. UseRMANInDDS is commented out and
set to FALSE in the WS distribution package. Refer to the DDS 4.5.2 Reference Guide
for more information on using DDS to generate RMAN maneuver instructions in XML.
The second way is to use RMAN-based routing manuevers generated by Web Services.
To do this, your DetermineRouteRequest must specify routeQueryType=RMAN.
The RouteInstructionsRequest element specifies which maneuver rules file to
use. Whatever maneuver rules files is specified must be found in /server/
Tomcat6.0.18/webapps/openls/WEB-INF/classes/com/telcontar/
openls/server/route/rules.
Note: The OpenLS exception “Maneuver list or rules failed” is thrown
when the default (RTXT-based) routing is used. If this exception is thrown when you
are trying to use RMAN-based routing, check that the maneuver-rules.xml file is in
the Drill Down Server/rules folder.
Note: The “RMAN rules not present in WEB-INF/classes/com/
telcontar/openls/server/route/rules folder”<rules>.xml” exception
is thrown, when the named <rules>.xml file is not found.
Figure 4.31 shows Route11.xml which contains a usage example.
4-84
October 15, 2010
Figure 4.31. Route11.xml Example Request
<ns1:XLS version="1" ns1:lang="en" xmlns:ns1="http://www.opengis.net/xls">
<ns1:RequestHeader sessionID="999" clientPassword="abc123" clientName="someclient"/>
<ns1:Request methodName="DetermineRouteRequest" version="1.0" maximumResponses="25" requestID="10">
<ns1:DetermineRouteRequest provideRouteHandle="false" routeQueryType="RMAN">
<ns1:RoutePlan>
<ns1:WayPointList>
<ns1:StartPoint>
<ns1:freeFormAddress>1 First St.,11111</ns1:freeFormAddress>
</ns1:Address>
</ns1:StartPoint>
<ns1:EndPoint>
<ns1:freeFormAddress>399 3rd ave, 11111</ns1:freeFormAddress>
</ns1:Address>
</ns1:EndPoint>
</ns1:WayPointList>
</ns1:RoutePlan>
<ns1:RouteInstructionsRequest rules="maneuver-rules"/>
</ns1:Request>
</ns1:XLS>
4.6.4.1.1 Using Example Maneuver Rules Files
The following four example maneuver rules files are available for use with RMANbased routing:
1. example-rules-01.xml file produces simple driving directions with no turn
maneuvers
2. example-rules-02.xml file introduces turn maneuvers (turn angles) in driving
directions
3. example-rules-03.xml shows how DDS output tokens are translated and
presented to the user as driving directions
4. example-rules-04.xml
To run these examples, use the Driving Directions tab on the Web-based
Console. Select the RMAN rules checkbox and enter a start and end address. examplerules-01 shows the recommended elements and simple driving directions rules.
Figure 4.32. example-rules-01
<route-instructions xmlns='http://decarta.com/dds/ws/routeInstructions'
xsi:schemaLocation='http://decarta.com/dds/ws/routeInstructions file:/C:/project/webservices/schema/RouteInstructions.xsd'>
<departure-maneuver>
<instruction>Begin on ${current-road} heading ${OHED} towards ${next-road}. </instruction>
</departure-maneuver>
<arrival-maneuver>
<instruction>Arrive at destination</instruction>
</arrival-maneuver>
4-85
October 15, 2010
<maneuver id="turn">
<instruction>Turn onto ${next-road}.</instruction>
</maneuver>
</route-instructions>
The routeInstructions element contains three XML-specific items, which
validating editors require to validate, or find errors in, the documents:
1. an xmlns (XML Namespace) declaration, which declares that unprefixed elements
in the document are defined in the namespace http://decarta.com/dds/ws/
routeInstructions
2. a declaration of the xsi prefix
3. a use of the xsi:schemaLocation attribute to point to the XML schema defining
the namespace declared in the xmlns declaration. When you are developing, you
should point the xsi:schemaLocation attribute to wherever you keep
RouteInstructions.xsd. However, in a production environment, an xmlns
declaration is not needed and no declaration of the xsi prefix is necessary in the
route-instructions element, though they do no harm.
Note: When you create your own maneuver files, it is strongly recommended that
you develop any XML document using a validating editor. It must be validated against
the RouteInstructions schema, which is found in web services\docs\xmlschema\RouteInstructions.xsd.
instruction
There are three elements specific to producing driving directions in the instruction
element shown in the example-rules-01 file:
1. departure-maneuver generates a special instruction for leaving the origin of the
route
2. arrival-maneuver generates a special instruction for arriving at the destination
3. maneuver generates an instruction for each output group from RMAN
When the DetermineRouteRequest from Route11.xml is executed, and
rules=example-rules-01 is specified, the following text is produced:
Figure 4.33. Driving Directions Results from example-rules-01.xml
${variable}
A special syntax ${variable}, as shown in the instruction element, is used to
replace the “dollars variable” with information reported by RMAN. You can use any
output from RMAN as a “dollars variable”. For example, ${OHED} caused the word
“South” to appear in the departure maneuver. The value of the DDS output keyword
OHED is substituted into the instruction for the departure maneuver.
4-86
October 15, 2010
In addition to all the RMAN output keywords used as “dollars variables”, the following
two special “dollars variables” are not DDS output keywords:
• current-road
• next-road.
In most cases, Web Services uses the values of the DDS SN and DSTR output
keywords for these variables. However, in cases where the SN or DSTR are empty or
where the road name is RAMP, Web Services uses a smart algorithm to produce a
reasonable value for current-road and next-road.
The example-rules-01 file does not produce directions that tell the user which
direction to turn onto 3rd Ave. The example-rules-02.xml file demonstrates how
to introduce turn angles into instructions.
Figure 4.34. example-rules-02
<turns>
<turn-angle min="-20" max="20" text="Continue"/>
<turn-angle min="20" max="45" text="Bear right"/>
<turn-angle min="-45" max="-20" text="Bear left"/>
<turn-angle min="45" max="95" text="Turn right"/>
<turn-angle min="-95" max="-45" text="Turn left"/>
<turn-angle min="95" max="135" text="Turn sharp right"/>
<turn-angle min="-135" max="-95" text="Turn sharp left"/>
<turn-angle min="135" max="180" text="Make right U-Turn"/>
<turn-angle max="-135" min="-180" text="Make left U-Turn"/>
</turns>
<arrival-maneuver>
</arrival-maneuver>
<instruction>$TURN-ANGLE{TANG} onto ${next-road}.</instruction>
</maneuver>
These rules produce instructions that include the direction in which the driver should
turn (note highlighting in yellow below).
The turn element includes a translation table that converts the DDS turn angle output
(TANG) into human readable text.
In order to pass the keyword TANG through the <turns> table, note the syntax
$TURN-ANGLE{TANG}. This is a special form of “dollars variable” which instructs
4-87
October 15, 2010
Web Services to post process the TANG output using the <turns> table to format the
text that goes into the driving instruction.
Users familiar with DDS know that many of the DDS keyword output values must be
interpreted (translated) before being presented to the end user. For example, the DIST
keyword reports the distance as, for example DIST=R1.54. The meaning of “R1.54”
is “1.54 Miles”.
The RMAN maneuver rules provides a syntax for accessing various pieces of output
tokens, and for translating those pieces before presenting them to the user as driving
directions. Example-rules-03.xml introduces the concept of a translation table,
and the context of token fields.
Figure 4.36. example-rules-03.xml
<translations>
<translate from="^R$" to="Miles"/>
</translations>
<turns>
</turns>
<arrival-maneuver>
</arrival-maneuver>
<instruction>Drive for ${DIST.VAL} $TRANSLATE{DIST.UOM}. Turn $TURN-ANGLE{TANG} onto ${next-road}. </instruction>
</maneuver>
Note that {DIST.VAL} extracted the distance value from the DDS DIST keyword,
while {DIST.VAL} extracted the Units Of Measure from the DIST keyword. The
$TRANSLATE{DIST.UOM} was used to convert “R”, the DDS Unit Of Measure to
“Miles”, which is what a user expects.
The translations table contains a single <translate> directive. The translate
directive applies a regular expression in the ‘from’ attribute. In this case, the regular
4-88
October 15, 2010
expression is ^R$ which means “beginning of input, followed by R, followed by end
of input”. The “to” attribute is the literal text which will be produced if the regular
expression matches against the input.
Real datasets are more complicated than the Stickville dataset. In a real dataset, RMAN
generates many maneuvers that may be as minor as following a road around a bend.
Good printable driving directions ignore the vast majority of the minor route guidance
maneuvers that RMAN produces. Therefore, the <ignore> directive is as important as
<maneuver>.
Because Stickville is such a simple dataset, none of the maneuvers in a route is
superfluous or ignorable. However, in the real world, superfluous maneuvers are
common. Therefore, example-rules-04.xml should be run on a real dataset, using
real addresses instead of Stickville addresses. Example-rules-04.xml
demonstrates how to ignore maneuvers that are commonly generated between
segments of roads where, despite the highway route number remaining the same, a
vanity name is introduced. Good driving directions should ignore such minor name
changes.
Figure 4.38. example-rules-04.xml
<translations>
<translate from="^R$" to="Miles"/>
</translations>
<turns>
</turns>
<arrival-maneuver>
</arrival-maneuver>
<ignore id="limited access or arterial route name doesn't change">
<outputgroup not-present="SGNB"/>
<road-name-unchanged name-components="RN"/>
<road-use-change from="1" to="1,2"/>
</ignore>
<instruction>Drive for ${DIST.VAL} $TRANSLATE{DIST.UOM}. Turn $TURN-ANGLE{TANG} onto ${next-road}. </instruction>
</maneuver>
The ignore element controls whether or not an RMAN output group is ignored. All
ignore elements are processed before maneuver elements are processed. An
4-89
October 15, 2010
ignore element is allowed to contain a variety of conditional elements. All of the
conditions must evaluate to true, in order for an output group to be ignored.
In the example above, the output-group element is used to prevent maneuvers from
being ignored if SGNB is present in the RMAN output group. The presence of an SGNB
token in the output group indicates that there is “sign beginning” information present.
Whenever signage begins, it would be a bad idea to ignore the maneuver. The
output-group element can be used with either present or not-present
attributes.
The road-name-unchanged element is used to specify that the route name (RN)
does not change between the two segments of the maneuver.
Finally, the road-use-change element is used to specify that the road-use must
change from a “1” (limited access road/highway) to a “1”or a “2” (arterial). For
general information road network connectivity conditions, refer to the Uniform Data
Model Reference Documentation.
The net effect of the three conditional elements in the ignore element is to say
“ignore RMAN output groups for which there is no SGNB token and the RN remains
constant throughout the maneuver, and the first segment of the maneuver is a highway
which either continues on a highway, or becomes an arterial road.”
For troubleshooting maneuver rules files, see “Maneuver Generation Debugging” on
page 3-23.
4-90
October 15, 2010
4.7 Scrolling Service
Scrolling Service requests and responses are all identical to the standard high level
Figure 4.39. The Request/Response Elements of Scrolling Service
Scroll01.xml example request
Scroll01.xml example response
<ns1:Request version="1.0" requestID="1" methodName="ScrollRequest">
<ns1:ScrollRequest scrollOn="saint" countryCode="USA" >
<ns1:Place type="Municipality">New York</ns1:Place>
</ns1:ScrollRequest>
</ns1:Request>
<ns1:ScrollResponse>
<ns1:Streets>[
{streetname:"SAINT THERESA AVE",vector:[8,4084921,-7383051,5,-35,5,45,8,-90,9,-90,8,-89,5,-90,5,-89]},
{streetname:"SAINT STEPHENS PL",vector:[11,4057813,-7411824,-56,-48,36,-27,-7,-10,-64,-139,-34,-73,-19,-42,-9,-21,-1,-3,1,-3,29,-50]},
{streetname:"SAINT RAYMONDS AVE",vector:[2,4083745,-7385540,10,-32]},
{streetname:"SAINT PETERS AVE",vector:[8,4083853,-7384458,64,-95,64,94,45,-68,44,-66,12,-14,78,-103,119,-162]},
{streetname:"SAINT PAULS PL",vector:[3,4083600,-7390350,18,-66,33,119]},
{streetname:"SAINT PAULS CT",vector:[2,4065068,-7396262,28,144]},
{streetname:"SAINT PAULS AVE",vector:[28,4062619,7408418,28,3,42,8,15,3,9,3,26,10,13,7,37,25,6,4,18,10,25,17,12,8,23,17,42,
34,24,22,44,50,9,11,9,11,33,33,87,107,38,43,10,10,46,40,11,8,13,7,15,7,35,1
1,30,10]},
{streetname:"SAINT PAULS AVE",vector:[9,4063319,7407899,87,29,80,24,42,14,99,29,44,6,16,1,58,1,27,1]},
{streetname:"SAINT PAUL AVE",vector:[3,4085227,-7382853,183,-137,144,73]},
{streetname:"SAINT PATRICKS PL",vector:[7,4056971,7414439,63,37,15,9,4,2,7,0,10,-1,59,-12]}]
</ns1:Streets>
<ns1:BoundingBox>
</ns1:BoundingBox>
</ns1:ScrollResponse>
</ns1:Response>
4.7.1 Request
shown in the example Scrolling Service request.
4-91
October 15, 2010
Scrolling Service
4.7.1.1 methodName
The value of methodName is ScrollRequest for a scrolling service request.
4.7.1.2 ScrollRequest
The ScrollRequest element includes all the main parts of a specific street name
lookup requestor a city name. ScrollRequest specifies that the streetnames or city
names that are the closest matching streets or city names are returned. Additional
information about the desired street name to use as selection criteria such as country
code, and place type are also included in the request.
4.7.1.2.1 ScrollOn
ScrollOn element identifies the street name or part of the street name that needs to
be scrolled on.
4.7.1.2.2 ScrollType
ScrollType element identifies the city name needs to be scrolled on.
CountrySubDivision must be present in the input.
4.7.2 Response
4.7.2.1 ScrollResponse
The ScrollResponse element returns the results of street names or of city names in
the request. The resulting street name and respective vectors which match the
ScrollOn keyword are reported in the Streets element and follow JSON standards.
4-92
CHAPTER 5
This chapter explains and illustrates the XML formats for queries and responses used
in fleet services DDS Web Services.
To enable fleet services, see “Enabling DDS Web Services Fleet Services” on page
3-17.
5-1
October 15, 2010
Dispatch Service
5.1 Dispatch Service
Dispatch Service requests and responses are all identical to the standard high level
Requests and Responses” on page 4-4. For a complete details of the Dispatch Service,
refer to the DispatchService.xsd in the install_dir\docs\xml-schema\fleet\.
Figure 5.1 shows the main sub-elements of the Request element, which distinguish
Dispatch Service requests and responses.
Figure 5.1. The Request/Response Elements of Dispatch Service.
Dispatch02.xml example request
Dispatch02.xml example response
<ns1:XLS version="1.0" ns1:lang="en" xmlns:ns1="http://www.opengis.net/
xls">
<ns1:RequestHeader sessionID="-" configuration="fleet"
clientPassword="abc123" clientName="someclient"/>
<ns1:Request requestID="10" methodName="DispatchRequest"
version="1.0" maximumResponses="1">
<ns1:DispatchRequest>
<ns1:BestVehicleForJobRequest returnManeuver="true"
order="DISTANCE">
<ns1:Job ID="1234567">
<ns1:Position>33.640137 -81.254883</ns1:Position>
<ns1:Schedule>2010-03-20T11:43:25.906+08:00</ns1:Schedule>
</ns1:Job>
<ns1:VehicleList>
<ns1:Vehicle ID="7654321">
<ns1:Position>
<ns2:pos>33.818663 -80.878602</ns2:pos>
</ns2:Point>
<ns1:Time begin="2010-03-19T11:43:25.953+08:00"/>
</ns1:Position>
</ns1:Vehicle>
<ns1:Position>
<ns3:pos>33.828663 -80.878602</ns3:pos>
</ns3:Point>
<ns1:Time begin="2010-03-19T11:43:25.953+08:00"/>
</ns1:Position>
</ns1:Vehicle>
<ns1:Position>
<ns4:pos>33.838663 -80.878602</ns4:pos>
</ns4:Point>
<ns1:Time begin="2010-03-19T11:43:25.953+08:00"/>
</ns1:Position>
</ns1:Vehicle>
</ns1:VehicleList>
</ns1:BestVehicleForJobRequest>
</ns1:DispatchRequest>
<ns1:XLS rel="4.5.2" version="1.0" ns1:lang="en" xmlns:ns1="http://
www.opengis.net/xls">
<ns1:ResponseHeader sessionID="-"/>
<ns1:Response requestID="10" version="1.0" numberOfResponses="0">
<ns1:DispatchResponse>
<ns1:BestVehicleForJobResponse>
<ns1:Position>
<ns2:pos>33.818663 -80.878602</ns2:pos>
</ns2:Point>
<ns1:Time begin="2010-03-19T11:43:25.953+08:00"/>
</ns1:Position>
</ns1:Vehicle>
<ns1:Route>
<ns1:RouteID>jwAAAHhWNBIAAAAAjwAAAF8YClvGeq/
YNPBj1BUIQUmX+29RrAJPSvwm/
Kkt8GPUFAAuSgQf+IEsmPUFIgArWgFB/wIOTvwGPUEEUEr9J/
O1IfBj1BMCO0oDoPYFV8Y9QTYFZUr9UADUYeGPUE4DaEr4Kf7jZagBVEb
5RFZF+Bjg8QNWSvJE8Ac7pgNJWv7X89us</ns1:RouteID>
<ns1:Eta>4140</ns1:Eta>
</ns1:Route>
<ns1:RouteInstruction description="route maneuver 1" tour="0"
duration="PT0H0M0S">
<ns1:Instruction>Proceed Northwest on BANKS LN</
ns1:Instruction>
<ns1:distance value="0.00"/>
</ns1:BestVehicleForJobResponse>
</ns1:DispatchResponse>
<ns1:RouteInstruction description="route maneuver 7" tour="0"
<ns1:Instruction>Turn sharp right onto PINE PLAIN RD/SC-65
.1:Instruction>
5-2
</ns1:BestVehicleForJobResponse>
October 15, 2010
5.1.1 Requests
shown in the example Dispatch Service request.
5.1.1.1 methodName
The RequestHeader follows the standard OpenLS format. The outermost level of
the Request also follows the standard OpenLS format. The only variability is that the
methodName attribute’s value specifies that this is a Dispatch Service’s request (value
DispatchRequest).
For example, the outer level of the Request in both sample XML requests
Dispatch02.xml and Dispatch02.xml are the following:
<ns1:Request maximumResponses="2" requestID="10" version="1.0"
methodName="DispatchRequest">
- <ns1:DispatchRequest>
Of course, in real usage the values of the other attributes will vary.
5.1.1.2 DispatchRequest
A dispatch service request will typically specify whether the search is for the best
vehicle for a positioned task (job) (BestVehicleForJobRequest), or for the best
job for the vehicles (BestJobForVehicleRequest). Dispatch service orders
responses by DISTANCE or TIME. Additionally, the location of the job(s) or task(s) to
be found, job ID(s), vehicles, time restrictions, the sort order of responses, routing
preferences, and vehicle IDs can also be specified. For information on
RoutePreference see “RoutePlan” on page 4-75.
The two main requests include a structure (either the job or the vehicle) and a list (of
the possible vehicles to get to the job, or a list of the possible jobs for the vehicles). In
the following BestJobForVehicle request, a list of jobs (Job List) with positions
and time restrictions are specified for a specific vehicle (Vehicle ID).
<ns1:DispatchRequest>
<ns1:BestJobForVehicleRequest order="TIME" returnManeuver="true">
<ns1:JobList>
<ns1:Job ID="1234567">
</ns1:Job>
<ns1:Job ID="1234568">
</ns1:Job>
<ns1:Job ID="1234569">
5-3
October 15, 2010
Dispatch Service
</ns1:Job>
</ns1:JobList>
<ns1:Position>
<ns2:pos>33.818663 -80.878602</ns2:pos>
</ns2:Point>
<ns1:Time begin="2010-03-19T11:57:38.843+08:00"/>
</ns1:Position>
</ns1:Vehicle>
</ns1:BestJobForVehicleRequest>
</ns1:DispatchRequest>
5.1.1.2.1 BestVehicleForJobRequest
BestVehicleForJobRequest contains a job structure and a vehicle list (a list with
several vehicle structures). Dispatch service will calculate each vehicle distance and
estimated time of arrival (ETA) to the job(s), sort the results, and return the best suited
vehicle to the client.
5.1.1.2.2 BestJobForVehicleRequest
BestJobForVehicleRequest contains several attributes including useTraffic
and returnManeuver. BestJobForVehicleRequest uses mostly the same
attributes as BestVehicleForJobRequest request.
5.1.1.2.3 order
Two possible values for ordering are DISTANCE (vehicle distance to the job) or TIME
(ETA). Both values return responses in ascending order.
5.1.1.2.4 useTraffic
The useTraffic values are as follows:
Value
5-4
Description
R
Real time traffic
P
Predictive traffic
H
Historic traffic
N
Do not use traffic
October 15, 2010
If the attribute useTraffic is set to R it means the current traffic information will be
used to compute distance and ETA. When the pending job is scheduled for the future
or in the past, the predictive traffic or historic traffic is supposed to be used, as
appropriate.
5.1.1.2.5 ReturnManeuver
When ReturnManeuver is set to TRUE the server returns the route instructions list.
When it is set to FALSE, no route instructions are returned in the response.
5.1.1.2.6 AvoidList
AvoidListType structure contains the list of areas, locations, and types of features in
which the route should avoid passing through. AvoidListType can be used with any
Dispatch Service request. The following example specifies that the returned route
avoid bridges:
<ns1:AvoidList>
<ns1:AvoidFeature>Bridges</
ns1:AvoidFeature>
</ns1:AvoidList>
5.1.1.2.7 useTraffic
When useTraffic is set, the Dispatch Service will calculate Distance and ETA
considering various types of traffic data. ‘R’ is used for real-time traffic, ‘P’ is used for
predictive traffic, ‘H’ is used for historic traffic, and ‘N’ is not to use traffic data. When
the jobs are in the future or in the past, the predictive traffic or historic traffic should
be used.
5.1.2 Responses
shown in the example Dispatch Service response.
5-5
October 15, 2010
Dispatch Service
5.1.2.1 DispatchResponse
The DispatchResponse element of the response is directly analogous to the
DirectoryRequest element of the request. It provides all the information about the
found POI(s) that were specified by the DirectoryRequest element.
5.1.2.1.1 BestJobForVehicleResponse
BestJobforVehicleResponse returns the list of elements requested, such as job
list specifying the job ID, job position, and job “schedule”, and the best vehicle, in the
form of vehicle ID and position. For example:
<ns1:DispatchResponse>
<ns1:BestJobForVehicleResponse>
<ns1:Job ID="1234567">
</ns1:Job>
<ns1:Route>
<ns1:RouteID>jwAAAHhWNBIAAAAAjwAAAF8YClvGeq/YNPBj1BUIQUmX+29RrAJPSvwm/
Kkt8GPUFAAuSgQf+IEsmPUFIgArWgFB/wIOTvwGPUEEUEr9J/
O1IfBj1BMCO0oDoPYFV8Y9QTYFZUr9UADUYeGPUE4DaEr4Kf7jZagBVEb5RFZF+Bjg8QNWSvJE8Ac7pgNJWv7Y892R</
ns1:RouteID>
<ns1:Eta>4140</ns1:Eta>
</ns1:Route>
<ns1:RouteInstruction description="route maneuver 1" tour="0" duration="PT0H0M0S">
<ns1:Instruction>Proceed Northwest on BANKS LN</ns1:Instruction>
<ns1:distance value="0.00"/>
<ns1:RouteInstruction description="route maneuver 2" tour="0" duration="P0DT0H9M3S">
<ns1:Instruction>Turn left onto OLD SWAMP RD.</ns1:Instruction>
<ns1:Instruction>Turn sharp right onto OLD STATE RD/OLD SWAMP RD/US-176 .</ns1:Instruction>
<ns1:Instruction>Turn sharp left onto OLD SANDY RUN RD/SC-31 .</ns1:Instruction>
<ns1:Instruction>Turn sharp right onto PINE PLAIN RD/SC-65 .</ns1:Instruction>
<ns1:Instruction>Continue onto MACK ST/SC-65 .</ns1:Instruction>
<ns1:Instruction>Turn left onto SOUTHBOUND RD/S MAIN ST/US-321 .</ns1:Instruction>
<ns1:Instruction>Continue onto SOUTHBOUND RD/US-321 S.</ns1:Instruction>
5-6
October 15, 2010
<ns1:Instruction>Continue onto SOUTHBOUND RD/US-321 .</ns1:Instruction>
<ns1:Instruction>Bear right onto WHETSTONE RD/SC-3 .</ns1:Instruction>
<ns1:Instruction>Turn right onto HOLLOW CREEK RD.</ns1:Instruction>
<ns1:Instruction>Arrive at destination</ns1:Instruction>
</ns1:BestJobForVehicleResponse>
5.1.2.1.2 BestVehicleForJobResponse
BestVehicleForJobResponse returns the list of elements requested, such as the
best vehicle for the job, in the form of vehicle ID and position. Route in distance and
ETA are returned. When route instructions are requested, route maneuvers for the best
vehicle are returned in the form of RouteInstruction elements.
5-7
October 15, 2010
Exclusion Zone Service
5.2 Exclusion Zone Service
The Exclusion Zone Service, a deCarta-specific extension to the OpenLS Core
Services, provides functionality for restricting route calculations so that specified
exclusion zones will not be considered when calculating a route. The service provides
functionality for adding, modifying, and removing exclusion zones through the
general XML request/response structure used for all DDS Web Services. The
xml_version, XLS, RequestHeader, and ResponseHeader elements of
Exclusion Zone Service requests and responses are all identical to the standard high
Request element, which distinguish Exclusion Zone Service requests and responses.
Figure 5.2. The Request/Response Elements of Exclusion Zone Service.
ExclusionZone01.xml example request
ExclusionZone01.xml example response
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
xls">
<ns1:RequestHeader sessionID="-" clientPassword="abc123"
configuration="stickville" clientName="someclient" />
<ns1:Request version="1.0" maximumResponses="25" requestID="10"
methodName="ExclusionZoneRequest">
<ns1:ExclusionZoneRequest>
<ns1:ZoneCreateRequest>
<ns1:ExclusionZone description="description of zone01"
name="zone01">
<ns1:Geometry>
<ns2:Polygon xmlns:ns2="http://www.opengis.net/gml">
<ns2:exterior>
<ns2:LinearRing>
<ns2:pos>41.0005 -72.0035</ns2:pos>
<ns2:pos>41.0015 -72.0035</ns2:pos>
<ns2:pos>41.0015 -72.0025</ns2:pos>
<ns2:pos>41.0005 -72.0025</ns2:pos>
</ns2:LinearRing>
</ns2:exterior>
</ns2:Polygon>
</ns1:Geometry>
<ns1:Properties>
<ns1:Property name="GroupID" value="10" />
<ns1:Property name="createdBy" value="ExclusionZone01" />
</ns1:Properties>
</ns1:ExclusionZone>
</ns1:ZoneCreateRequest>
</ns1:ExclusionZoneRequest>
</ns1:Request>
</ns1:XLS>
<ns1:XLS rel="4.5.2.sp02" ns1:lang="en" version="1.0" xmlns:ns1="http://
<ns1:Response numberOfResponses="1" requestID="10" version="1.0">
<ns1:ExclusionZoneResponse>
<ns1:ZoneCreateResponse>
<ns1:ExclusionZone id="1" description="description of zone01"
name="zone01"/>
</ns1:ZoneCreateResponse>
</ns1:ExclusionZoneResponse>
</ns1:Response>
</ns1:XLS>
Other examples of Exclusion Zone requests and responses can be found in:
<Installation Folder>\Web Services\ext\fleet\test_xml. Also,
sample code can be found in the following path: <Installation Folder>\Web
Services\ext\fleet\src\examples\fleet.
5-8
October 15, 2010
5.2.1 Requests
shown in the example exclusion zone request.
5.2.1.1 methodName
The value of methodName is ExclusionZoneRequest for an Exclusion Zone
request.
5.2.1.2 ExclusionZoneRequest
Exclusion Zone Service has the following three main functional areas, with specified
nested elements:
• create (ZoneCreateRequest), update(ZoneUpdateRequest), or delete
(ZoneDeleteRequest) an exclusion zone
• retrieve an exclusion zone (ZoneRetrieveRequest)
• use exclusion zones for routing (DetermineRouteRequest)
5.2.1.2.1 ZoneCreateRequest
The ZoneCreateRequest element contains the structure for creating an exclusion
zone request. It provides the ability for users to include the following information in
the request:
•
•
•
•
•
name
description
geometry
exclusion zone properties
list of restricted active times.
When the ZoneCreateRequest is received, the server saves the exclusion zone
information to a database and generates a unique exclusion zone ID. Exclusion zones
created under a given customer name can only be accessed by the same customer
name in subsequent requests.
Table 5.1. ZoneCreateRequest Examples and File Locations
JAVA Sample
XML Sample
ExclusionZone01.java
ExclusionZone01.xml
Description
Create a POLYGON
exclusion zone
5-9
October 15, 2010
Table 5.1. ZoneCreateRequest Examples and File Locations
JAVA Sample
XML Sample
Description
ExclusionZone02.xml
Create a CIRCLE
exclusion zone
ExclusionZone03.xml
Create a LINE
exclusion zone
ExclusionZone09.xml
Batch-create/bulkload exclusion zones
JAVA sample files can be found at <Installation Folder>\Web
Services\ext\fleet\src\examples\fleet. XML sample files can be found at
<Installation Folder>\Web Services\ext\fleet\test_xml.
5.2.1.3 ExclusionZone
The top-level element in a ZoneCreateRequest is an ExclusionZone tag. The
name and description of an exclusion zone are specified by the Name and
Description parameters of the ExclusionZone tag as follows:
<ns1:ExclusionZone description="description of zone01" name="zone01">
The ExclusionZone element main contain additional details of the exclusion zone
by the use of Geometry, Properties, or RestrictedActiveTimes elements as
described in the following sections.
5.2.1.3.1 Geometry
For Geometry, the values CircleByCenterPoint, Polygon, and LineString are
supported. The following is an example of a circle geometry:
<ns1:Geometry>
<ns2:CircleByCenterPoint numArc="1" xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>41.003 -72.001</ns2:pos>
<ns2:radius uom="M">10.0</ns2:radius>
</ns2:CircleByCenterPoint>
</ns1:Geometry>
The following is an example of a polygon geometry:
<ns1:Geometry>
<ns2:exterior>
<ns2:LinearRing>
<ns2:pos>41.0005 -72.0035</ns2:pos>
<ns2:pos>41.0015 -72.0035</ns2:pos>
<ns2:pos>41.0015 -72.0025</ns2:pos>
<ns2:pos>41.0005 -72.0025</ns2:pos>
5-10
October 15, 2010
</ns2:LinearRing>
</ns2:exterior>
</ns2:Polygon>
</ns1:Geometry>
The following is an example of a linear geometry:
<ns1:Geometry>
<ns2:LineString xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>41.002 -72.002</ns2:pos>
<ns2:pos>41.001 -72.002</ns2:pos>
</ns2:LineString>
</ns1:Geometry>
Exclusion zone properties are the metadata of an exclusion zone, and can be queried
for data retrieval. Only exclusion zones that match all of the properties in a search
criteria are returned.
5.2.1.3.2 Properties
The following is an example of the Properties section of a ZoneCreateRequest:
<ns1:Properties>
<ns1:Property name="GroupID" value="10"/>
<ns1:Property name="createdBy" value="ExclusionZone01"/>
</ns1:Properties>
5.2.1.3.3 RestrictedActiveTimes
RestrictedActiveTimes is a list of active times in which an Exclusion Zone is
active. If no restricted active times are defined at the time of creation, then the
Exclusion Zone is considered active at all times. When specifying the active time,
recurrence type can be either daily (D) or weekly (W). In the case of weekly, a day of
week can be M, T, W, H, F, A, or S. The time by default is considered GMT time and
is also stored as GMT time in the database.
Here are three different styles of expressing the same time 11:30:00 GMT:
<ns1:StartTime>11:30:00</ns1:StartTime>
<ns1:StartTime>11:30:00+00:00</ns1:StartTime>
<ns1:StartTime>11:30:00Z</ns1:StartTime>
The following is an example of the RestrictedActiveTimes section of a
ZoneCreateRequest:
<ns1:RestrictedActiveTimes>
<ns1:ActiveTime recurrenceType="W" weeklyRecurrenceDay="M">
<ns1:EndTime>14:00:00+00:00</ns1:EndTime>
</ns1:ActiveTime>
</ns1:RestrictedActiveTimes>
5-11
October 15, 2010
5.2.1.4 ZoneUpdateRequest
The ZoneUpdateRequest element contains the structure for requesting an update to
an exclusion zone stored on the server. Users can update exclusion zones with any of
the following information:
•
•
•
•
•
•
exclusion zone ID
exclusion zone name
exclusion zone description
geometry information
list of properties
list of restricted active times
When updating an exclusion zone, the new zone information overwrites the existing
exclusion zone record of the same exclusion zone ID. After an exclusion zone is
updated, the same zone ID is returned in the response to acknowledge this action.
The contents of the ZoneUpdateRequest are the same as a ZoneCreateRequest.
The ZoneUpdateRequest contains an ExclusionZone element. The
ExclusionZone element, in turn, may contain a Geometry element, a list of
Properties, and a list of RestrictedActiveTimes.
An example of a ZoneUpdateRequest can be found in ExclusionZone07.java
or ExclusionZone07.xml. JAVA sample files can be found at <Installation
Folder>\Web Services\ext\fleet\src\examples\fleet. XML sample files
can be found at <Installation Folder>\Web
Services\ext\fleet\test_xml.
5.2.1.5 ZoneDeleteRequest
The ZoneDeleteRequest contains only the exclusion zone ID number of the
exclusion zone to delete from the server database. The format of a
ZoneDeleteRequest is as follows:
<ns1:ZoneDeleteRequest>
<ns1:ID>2</ns1:ID>
</ns1:ZoneDeleteRequest>
An example of a ZoneDeleteRequest can be found in ExclusionZone08.java
or ExclusionZone08.xml. JAVA sample files can be found at <Installation
Folder>\Web Services\ext\fleet\src\examples\fleet. XML sample files
can be found at <Installation Folder>\Web
Services\ext\fleet\test_xml.
5-12
October 15, 2010
5.2.1.6 ZoneRetrieveRequest
The ZoneRetrieveRequest element contains the structure for requesting one or
more exclusion zones to be returned from the server. Users can retrieve exclusion
zones with one of the following information in the request:
• Exclusion Zone ID –OR–
• Zone Properties –OR–
• No Criteria (to retrieve all exclusion zones)
The ZoneRetrieveRequest element also accepts parameters which define which
portions of an exclusion zone to return.
Table 5.2. ZoneRetrieveRequest Examples and File Locations
JAVA Sample
XML Sample
Description
ExclusionZone04.xml
Retrieve all exclusion
zones
ExclusionZone05.xml
Retrieve an exclusion
zone with zone ID
ExclusionZone06.xml
Retrieve exclusion
zones with zone
properties
JAVA sample files can be found at <Installation Folder>\Web
5.2.1.6.1 ZoneRetrieveRequest return parameters
The following optional parameter are allowed as part of the ZoneRetrieveRequest
element:
• returnProperties=”true”
• returnGeometry=”true”
• returnRestrictedActiveTimes=”true”
For example, using only one parameter:
<ns1:ZoneRetrieveRequest returnProperties="true">
</ns1:ZoneRetrieveRequest>
Or, using all the parameters:
<ns1:ZoneRetrieveRequest returnProperties="true" returnGeometry="true" returnRestrictedActiveTimes="true">
5-13
October 15, 2010
5.2.1.6.2 ID
The ZoneRetrieveRequest may generate a request that requests exclusion zones
by exclusion zone ID. One or more ID elements may be used within the
ZoneRetrieveRequest element. For example:
<ns1:ZoneRetrieveRequest returnProperties="true" returnGeometry="true">
<ns1:ID>1</ns1:ID>
5.2.1.6.3 Properties
The ZoneRetrieveRequest may also generate a request that requests exclusion
zones by specifying one or more properties to search for using the Properties tag.
All exclusion zones that match all of the specified property/key values will be
returned. For example:
<ns1:ZoneRetrieveRequest returnProperties="true">
<ns1:Properties>
</ns1:Properties>
5.2.1.6.4 No Criteria
If a ZoneRetrieveRequest is created with no specified ID or Properties tags, it
will return all available exclusion zones. For example:
<ns1:ZoneRetrieveRequest/>
5.2.1.7 DetermineRouteRequest with Exclusion Zones
To request a route that avoids exclusion zones, use the attribute useExclusionZone
in the RoutePlan element of the DetermineRouteRequest. See “RoutePlan” on
page 4-75 for more information.
The following is a sample route request using the useExclusionZone attribute:
<ns1:RoutePlan useExclusionZone="true">
<ns1:WayPointList>
<ns1:StartPoint>
<ns1:freeFormAddress>1 First St., Stickville, NY 11111</ns1:freeFormAddress>
</ns1:Address>
</ns1:StartPoint>
<ns1:EndPoint>
<ns1:freeFormAddress>399 3rd ave, Stickville, NY 11111</ns1:freeFormAddress>
</ns1:Address>
5-14
October 15, 2010
</ns1:EndPoint>
</ns1:WayPointList>
</ns1:RoutePlan>
An example of a DetermineRouteRequest can be found in
ExclusionZone10.java or ExclusionZone10.xml. JAVA sample files can be
found at <Installation Folder>\Web
5.2.2 Responses
down in the example exclusion zone Response.
5.2.2.1 ExclusionZoneResponse
Each exclusion zone request has a corresponding exclusion zone response. These
responses are encapsulated in the ExclusionZoneResponse element in the returned
XML. The responses contained within the ExclusionZoneResponse, with
specified nested elements, are one of the following:
•
•
•
•
Create response (ZoneCreateResponse)
Update response (ZoneUpdateResponse)
Delete response (ZoneDeleteResponse)
Retrieve an exclusion zone response (ZoneRetrieveResponse)
5.2.2.2 ZoneCreateResponse
In response to a ZoneCreateRequest, the server will return an
ExclusionZoneResponse which contains a ZoneCreateResponse element. The
ZoneCreateResponse element contains one or more ExclusionZone elements
with the ID, name, and description of the created ExclusionZone. For example:
<ns1:ZoneCreateResponse>
<ns1:ExclusionZone id="1" description="description of zone01" name="zone01"/>
</ns1:ZoneCreateResponse>
The ZoneCreateResponse may contain more than one element if the
ZoneCreateRequest was a batch operation, loading a set of exclusion zones onto
the server simultaneously.
5-15
October 15, 2010
5.2.2.3 ZoneUpdateResponse
In response to a ZoneUpdateRequest, the server will return an
ExclusionZoneResponse which contains a ZoneUpdateResponse element. The
ZoneUpdateResponse element contains an ExclusionZone element with the ID,
name, and description of the updated ExclusionZone. For example:
<ns1:ZoneUpdateResponse>
<ns1:ExclusionZone id="1" description="description of zone01" name="zone01"/>
</ns1:ZoneUpdateResponse>
5.2.2.4 ZoneDeleteResponse
In response to a ZoneDeleteRequest, the server will return an
ExclusionZoneResponse which contains a ZoneDeleteResponse element. The
ZoneDeleteResponse element contains an ExclusionZone element with the ID
of the deleted ExclusionZone. For example:
<ns1:ZoneDeleteResponse>
<ns1:ExclusionZone id="1"/>
</ns1:ZoneDeleteResponse>
5.2.2.5 ZoneRetrieveResponse
In response to a ZoneRetrieveRequest, the server will return an
ExclusionZoneResponse which contains a ZoneRetrieveResponse element.
The ZoneRetrieveResponse element contains one or more ExclusionZone
elements. Depending on the request, the returned ExclusionZone elements may
contain some or all of the contents of the returned exclusion zone.
The ExclusionZone elements use the same format as the ZoneCreateRequest:
•
•
•
•
ExclusionZone
Geometry
Properties
RestrictedActiveTime
The following is an example of an ZoneRetrieveResponse:
<ns1:ZoneRetrieveResponse count="3">
<ns1:ExclusionZone id="1" name="zone01" description="description of zone01">
<ns1:Properties>
</ns1:Properties>
5-16
October 15, 2010
<ns1:Properties>
</ns1:Properties>
<ns1:Properties>
</ns1:Properties>
</ns1:ZoneRetrieveResponse>
5-17
October 15, 2010
Geofencing Service
5.3 Geofencing Service
Geofencing Service requests and responses are all identical to the standard high level
Requests and Responses” on page 4-4. For complete details of the Geofencing
Service, refer to the GeofencingService.xsd in the install_dir\docs\xmlschema\fleet\. Figure 5.3 shows the main sub-elements of the Request element,
which distinguish Geofencing Service requests and responses.
Figure 5.3. The Request/Response Elements of Geofencing Service
Geofencing01.xml example request
Geofencing01.xml example response
<ns1:XLS version="1.0" ns1:lang="en" xmlns:ns1="http://www.opengis.net/
xls">
<ns1:RequestHeader sessionID="-" configuration="stickville"
clientPassword="abc123" clientName="someclient"/>
<ns1:Request methodName="GeofencingRequest" version="1.0"
maximumResponses="25" requestID="10">
<ns1:GeofencingRequest>
<ns1:FenceCreateRequest>
<ns1:Geofence violationType="I" description="description of
MyFence01" name="MyFence01">
<ns1:Geometry>
<ns2:exterior>
<ns2:LinearRing>
<ns2:pos>41.002 -72.003</ns2:pos>
<ns2:pos>41.002 -72.002</ns2:pos>
<ns2:pos>41.001 -72.002</ns2:pos>
<ns2:pos>41.001 -72.003</ns2:pos>
</ns2:LinearRing>
</ns2:exterior>
</ns2:Polygon>
</ns1:Geometry>
<ns1:Properties>
<ns1:Property value="5" name="GroupID"/>
<ns1:Property value="Geofencing01" name="createdBy"/>
</ns1:Properties>
<ns1:ActiveTime recurrenceType="D">
</ns1:ActiveTime>
</ns1:Geofence>
</ns1:FenceCreateRequest>
</ns1:GeofencingRequest>
</ns1:Request>
</ns1:XLS>
<ns1:XLS rel="4.5.2" version="1.0" ns1:lang="en" xmlns:ns1="http://
<ns1:GeofencingResponse>
<ns1:FenceCreateResponse>
<ns1:Geofence description="description of MyFence01"
violationType="I" id="1" name="MyFence01"/>
</ns1:FenceCreateResponse>
</ns1:GeofencingResponse>
</ns1:Response>
</ns1:XLS>
5-18
October 15, 2010
5.3.1 Requests
The following sections provide some additional explanation of the main elements of
Geofencing Service requests.
5.3.1.1 methodName
The value of methodName is GeofencingRequest for a geofencing request.
5.3.1.2 GeofencingRequest
Geofencing Service has three main functional areas, with specified nested elements, as
follows:
• create (FenceCreateRequest), update (FenceUpdateRequest), or delete (or
drop) (FenceDeleteRequest) a geofence
• retrieve a geofence (FenceRetrieveRequest)
• check if route violated geofence (FenceViolationCheckRequest).
5.3.1.3 FenceCreateRequest
The GeofencingRequest element allows users to include the following information
in the request: name, description, geometry information, violation type, geofencing
properties, a list of restricted active times, and meta info used for geofence rendering
attributes.
When the FenceCreateRequest request is received, the server saves the geofence
information to a database and generates a unique geofence ID. Geofences created
under a given customer name can only be accessed by the same customer name in
subsequent requests.
For Geometry, the values Circle and Polygon are supported. For example:
<ns1:Geometry>
<ns2:CircleByCenterPoint numArc="1"
xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>37.201301 121.532301</ns2:pos>
<ns2:radius uom="KM">10.0</ns2:radius>
Geofence properties are the metadat of a geofence and can be queried for data
retrieval. Only geofences that match all the properties in a search criteria are returned.
You can define geofence properties in a manner that is suitable to your application,
5-19
October 15, 2010
Geofencing Service
such as geofence grouping or client entity association, etc. The Geofence group
property allows a user to provide a non-unique string, that is useful for users to
associate this geofence with others. Meta info by default is used by deCarta JavaScript
tool to store the rendering attributes and is used by the tool to render the geofence in
various styles based on those attributes.
5.3.1.3.1 RestrictedActiveTimes
RestrictedActiveTimes is a list of active times in which a geofence is active. If
no restricted active times are defined at the time of creation, then the geofence is
considered active at all times. During the geofence violation check, only the active
geofences are considered for violation checks.
When specifying the active time, recurrence type can be either daily (D) or weekly (W).
In the case of weekly, a day of week can be M, T, W, H, F, A, or S. The time by default is
considered GMT time and is also stored as GMT time in the database.
Here are three different styles of expressing the same time 11:30:00 GMT:
<ns1:StartTime>11:30:00</ns1:StartTime>
<ns1:StartTime>11:30:00Z</ns1:StartTime>
5.3.1.3.2 violationType
The element violationType can be either inside (I) or outside (O) the geofence. It
is used at the time when a given GPS point is checked against the geofence. If the
point falls within the geofence, and geofence violationType set to I, a violation is
determined. If the point falls outside the geofence, and the geofence violationType
is set to O, a violation has not occurred.
5.3.1.3.3 returnViolationOnly
When the attribute returnViolationOnly is set to true, only the check points that
have geofence violations are returned. When set to false, all the check points are
returned. Default is true.
5.3.1.3.4 FenceUpdateRequest
FenceUpdateRequest overwrites the existing geofence record of a given geofence
ID.
5-20
October 15, 2010
5.3.1.3.5 FenceDeleteRequest
FenceDeleteRequest deletes the existing geofence record of a given geofence ID.
The same geofence ID is returned in the response, acknowledging the deletion.
5.3.1.3.6 FenceRetrieveRequest
FenceRetrieveRequest allows you to retrieve geofences with geofence IDs and
geofence properties in the request. You can retrieve geofences using any or a
combination of the following:
• geofence ID
• geofence properties (such as returnProperties, returnGeometry, and
returnRestrictedActiveTimes)
In the request, returnGeometry, returnProperties, and
returnRestrictedActiveTimes are three optional attributes to ask for detail
information returned in the response.When no criteria are defined, by default all
geofence records under that client name are returned.
5.3.1.3.7 FenceViolationCheckRequest
With FenceViolationCheckRequest, an application can check geofence
violations with the following information as the input:
• GPS points with lat/lon coordinates and date/time
• Geofence lookup criteria which can be either a geofence ID or geofence properties.
The following Geofencing09.xml file shows an example of a fence violation check
request:
<ns1:XLS version="1.0" ns1:lang="en" xmlns:ns1="http://www.opengis.net/xls">
<ns1:RequestHeader sessionID="-" configuration="stickville" clientPassword="abc123" clientName="someclient"/>
<ns1:Request methodName="GeofencingRequest" version="1.0" maximumResponses="25" requestID="10">
<ns1:FenceViolationCheckRequest returnViolationOnly="false">
<ns1:CheckPoint>
<ns2:pos xmlns:ns2="http://www.opengis.net/gml">41.0015 -72.0035</ns2:pos>
</ns1:CheckPoint>
<ns1:CheckPoint>
</ns1:CheckPoint>
</ns1:FenceViolationCheckRequest>
</ns1:Request>
</ns1:XLS>
5-21
October 15, 2010
Geofencing Service
5.3.2 Responses
The following sections provide some additional explanation of the main elements in
the Geofencing Service.
5.3.2.1 GeofencingResponse
The GeofencingResponse returns the results of the geofence request.
5.3.2.1.1 FenceCreateResponse
A FenceCreateResponse returns the assigned geofence ID and if part of the
request, the name, description, violation type, and meta info.
5.3.2.1.2 FenceUpdateResponse
A FenceUpdateResponse returns the assigned geofence ID and if part of the
request, the name, description, violation type, and meta info.
5.3.2.1.3 FenceDeleteResponse
A FenceDeleteResponse returns the geofence ID.
5.3.2.1.4 FenceRetrieveResponse
FenceRetrieveResponse returns the geofences that match the requested criteria. A
count in the response indicates the number of geofences that are returned. In the
following Geofencing04.xml example, a FenceRetrieveRequest is made using
a geofence ID.
<ns1:XLS version="1.0" ns1:lang="en" xmlns:ns1="http://www.opengis.net/xls">
<ns1:RequestHeader sessionID="-" configuration="stickville" clientPassword="abc123" clientName="someclient"/>
<ns1:Request methodName="GeofencingRequest" version="1.0" maximumResponses="25" requestID="10">
<ns1:FenceRetrieveRequest returnRestrictedActiveTimes="true" returnProperties="true" returnGeometry="true">
<ns1:ID>1</ns1:ID>
</ns1:FenceRetrieveRequest>
</ns1:Request>
</ns1:XLS>
5-22
October 15, 2010
The response:
</ns1:XLS><?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:XLS rel="4.5.2" version="1.0" ns1:lang="en" xmlns:ns1="http://www.opengis.net/xls">
<ns1:FenceRetrieveResponse count="1">
<ns1:Geofence violationType="I" name="MyFence01" description="description of MyFence01" id="1">
<ns1:Geometry>
<ns2:CircleByCenterPoint numArc="1" xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>41.002 -72.003</ns2:pos>
<ns2:radius uom="M">100.0</ns2:radius>
</ns1:Geometry>
<ns1:Properties>
<ns1:Property value="Geofencing01" name="createdBy"/>
<ns1:Property value="5" name="GroupID"/>
</ns1:Properties>
<ns1:ActiveTime recurrenceType="D" weeklyRecurrenceDay=" ">
</ns1:ActiveTime>
</ns1:Geofence>
</ns1:FenceRetrieveResponse>
</ns1:Response>
</ns1:XLS>
5.3.2.1.5 FenceViolationCheckResponse
FenceViolationCheckResponse returns the response of the geofence violation
check as shown in the following response to Geofencing09.xml example:
<ns1:XLS rel="4.5.2" version="1.0" ns1:lang="en" xmlns:ns1="http://www.opengis.net/xls">
<ns1:FenceViolationCheckResponse>
<ns1:CheckPointResult checkPointIndex="1" isViolation="false">
</ns1:CheckPointResult>
<ns1:CheckPointResult checkPointIndex="2" isViolation="true">
<ns1:ViolatedGeofences>
<ns1:Geofence description="description of MyFence01" violationType="I" id="1" name="MyFence01"/>
</ns1:ViolatedGeofences>
</ns1:CheckPointResult>
</ns1:FenceViolationCheckResponse>
</ns1:Response>
</ns1:XLS>
5-23
October 15, 2010
Route Compliance Service
5.4 Route Compliance Service
Route Compliance Service requests and responses are all identical to the standard high
Requests and Responses” on page 4-4. For a complete details of the Route
Compliance Service, refer to the RouteComplianceService.xsd in the
install_dir\docs\xml-schema\fleet\. Figure 5.4 shows the main sub-elements of
the Request element, which distinguish Route Compliance Service requests and
responses.
Figure 5.4. The Request/Response Elements of Route Compliance Service
RouteCompliance04.xml example request
RouteCompliance04.xml example response
<ns1:XLS rel="4.5.2" ns1:lang="en" version="1.0" xmlns:ns1="http://
<ns1:RequestHeader configuration="fleet" clientPassword="abc123"
sessionID="-" clientName="someclient"/>
<ns1:Request maximumResponses="25" version="1.0" requestID="10"
methodName="RouteComplianceRequest">
<ns1:RouteComplianceRequest>
<ns1:RouteRetrieveRequest returnProperties="true"
returnGeometry="true">
<ns1:ID>97</ns1:ID>
</ns1:RouteRetrieveRequest>
</ns1:RouteComplianceRequest>
</ns1:Request>
</ns1:XLS>
<ns1:XLS rel="4.5.2" ns1:lang="en" version="1" xmlns:ns1="http://
<ns1:Response numberOfResponses="0" version="1.0" requestID="10">
<ns1:RouteComplianceResponse>
<ns1:RouteRetrieveResponse count="1">
<ns1:Route name="ROUTE002" metaInfo="metainfo"
description="description" id="97">
<ns1:Geometry>
<ns1:RouteID>WgAAAHhWNBIAAAAAWgAAAF8a8CepC3IA7Wbpyl0t/
hAAa0W3OoRn4XS3+ACBW0lTAalvXS3/
UwFrRdIvZZdLf4MAcEb+EkvXyRWoALENRv6uHoGfrQHgZ8i8VQc5AA==</
ns1:RouteID>
</ns1:Geometry>
<ns1:Buffer uom="MI" value="0.002"/>
<ns1:Properties>
<ns1:Property name="vehicle" value="1234567890987654320"/
>
</ns1:Properties>
</ns1:Route>
</ns1:RouteRetrieveResponse>
</ns1:RouteComplianceResponse>
</ns1:Response>
</ns1:XLS>
5.4.1 Requests
Route Compliance service requests.
For fleet applications, it is often necessary to enforce adherence to specific routes
when routing large trucks (HGV). The route may be optimized for fuel usage, distance
or hazmat restrictions. Customers can calculate a route using any route style, vehicle
5-24
October 15, 2010
parameter (truck, commercial, vehicle), and with or without traffic data. To avoid
triggering a false route compliance report, where a vehicle may have strayed off the
route, a buffer to the route may be created. You can set this buffer using Buffer and
identifying the unit of measure numeric value (i.e., 50 ft.).
The route can then be saved, assigned identification with a route ID and then
monitored against a vehicles’ GPS trails in real time or as a post process.
5.4.1.1 methodName
The value of methodName is RouteComplianceRequest for a Route Compliance
Service request.
5.4.1.2 RouteComplianceRequest
Route Compliance Service has three main functional areas, with specified nested
elements, as follows:
• create (RouteCreateRequest), update (RouteUpdateRequest), or delete
(RouteDeleteRequest) route compliance
• retrieve route compliance (RouteRetrieveRequest)
• check if route violated route compliance (ComplianceCheckRequest)
The RouteComplianceRequest element allows users to include the following
information in the request: name, description, geometry information, route
compliance properties, buffer, or meta info.
5.4.1.2.1 RouteCreateRequest
RouteCreateRequest allows you to assign a name to and create a description of
route compliance, add a geometry to the route compliance, assign a buffer area to the
route, attach meta info, and generate a route compliance ID.
When the RouteCreateRequest request is received, the server saves such route
compliance information to a database. Additionally, the client name input by the user
and system generated spatial key are stored in the database.
The routecompliance table stores the route name, description, meta info,
geometry, and buffer.
The routecompliance properties table stores the RouteComplianceID, and the
property name and the value.
5-25
October 15, 2010
5.4.1.2.2 RouteDeleteRequest
RouteDeleteRequest allows a client to delete route compliances with only the
RouteComplianceID. After the RouteComplianceID is deleted, the same ID is
returned in the response to acknowledge this action.
Here are the relevant lines for deleting a route compliance using a route compliance
ID:
<ns1:RouteDeleteRequest>
<ns1:ID>8</ns1:ID>
<ns1:ID>9</ns1:ID>
</ns1:RouteDeleteRequest>
5.4.1.2.3 RouteUpdateRequest
RouteUpdateRequest allows you to update a previously created route compliance,
using the route compliance ID. The request includes with following information in the
request: name, description, geometry information, route compliance properties, buffer,
meta info, and a route compliance ID.
The new route compliance information overwrites the existing record of a given route
compliance ID. After the route compliance of a given ID is updated, the same route
compliance ICD is returned in the response to acknowledge this action.
5.4.1.2.4 RouteRetrieveRequest
RouteRetrieveRequest allows you to retrieve route compliances with route
compliance IDs and route compliance properties in the request. You can retrieve route
compliances using any or a combination of the following:
• client name
• route compliance ID
• route compliance properties (such as returnProperty and returnGeometry)
The following is a route retrieval request based on client name and route compliance
properties:
<?xml version="1.0" encoding="UTF-8"?>
xls"
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
<ns1:RequestHeader clientName="admin" sessionID="999"
configuration="fleet" clientPassword="12345"/>
<ns1:Request methodName="RouteComplianceRequest" requestID="10"
<ns1:RouteComplianceRequest>
5-26
October 15, 2010
<ns1:RouteRetrieveRequest returnProperty="true"
returnGeometry="false">

</ns1:RouteRetrieveRequest>
</ns1:RouteComplianceRequest>
For example, users can retrieve the route compliances which have the property key/
value (deviceID=10) or users can retrieve the route compliances which has the
property key (deviceID).
If no search criteria is defined, all route compliances are returned.
5.4.1.2.5 Route Compliance Properties
Route Compliance properties are the metadat of a route compliance. You can
define any properties which make sense to your business use. Those properties can
also be used for the data retrieval queries, such as Property name="device_c1"
value="1000".
RouteComplianceID is stored in the “routecomplianceproperty” table, and
designates the RouteComplianceID to which the property name and value
belong:
5.4.1.2.6 Geometry
The route compliance services supports two types of geometry with the following
Geometry element:
1. When RouteID is nested in a Geometry element such as,
UwFrRdIvZZdLf4MAcEb+EkvXyRWoALENRv6uHoGfrQHgZ8i8VQc5AA==</
ns1:RouteID> the service saves the Route ID’s binary data directly to the
database.
2. When LineString is nested in a Geometry element such as:
<ns2:LineString xmlns:ns2="http://www.opengis.net/gml">
<ns2:pos>33.64062 -81.25517</ns2:pos>
<ns2:pos>33.64128 -81.25354</ns2:pos>
<ns2:pos>33.64171 -81.25233</ns2:pos>
</ns2:LineString>
then the service converts the LineString to RouteID using RTXT from the DDS
routing plug-in. The Route ID(s) binary data is stored in the database.
5-27
October 15, 2010
5.4.1.2.7 Buffer
Buffer defines the buffer around route using “value” and “uom” or unit of measure
such as <ns1:Buffer uom="KM" value="1.0"/>.
5.4.1.2.8 ComplianceCheckRequest
With ComplianceCheckRequest, an application can check route compliance
violations with following information as the input:
• GPS points with lat/lon coordinates
• Route compliance lookup criteria which can be either a route compliance ID or a
transmitted custom compliance route.
CheckPoint provides the point(s) in lat/lon format to compare to the route
compliance.
ComplianceLookupCriteria identifies the route compliance ID so that the points
can be checked against the identified route compliance for route violations, such as:
<ns1:ComplianceLookupCriteria>
<ns1:ID>5</ns1:ID>
5.4.2 Responses
the Route Compliance Service.
5.4.2.1 RouteComplianceResponse
The RouteComplianceResponse returns the results of the requested route
compliance.
5.4.2.1.1 RouteCreateResponse
A RouteCreateResponse returns the assigned route compliance ID, route name,
and meta info.
5-28
October 15, 2010
5.4.2.1.2 RouteDeleteResponse
A RouteDeleteResponse returns the route compliance ID of the deleted route
compliance, the route name, and meta info. An example:
<ns1:RouteDeleteResponse>
<ns1:Route metaInfo="metaInfo" name="route compliance
1" id="8" description="route compliacne description" />
<ns1:Route metaInfo="metaInfo" name="route compliance
1" id="9" description="route compliacne description" />
</ns1:RouteDeleteResponse>
5.4.2.1.3 RouteUpdateResponse
A RouteUpdateResponse returns the assigned route compliance ID, route name,
and meta info.
5.4.2.1.4 RouteRetrieveResponse
The RouteRetrieveResponse includes a count and then any of the elements specified in
the RouteRetrieveRequest such as property elements and/or the geometry element.
The following example show both property elements and geometry elements:
<ns1:RouteRetrieveResponse count="2">
<ns1:Route metaInfo="metaInfo" id="5" name="name3"
description="description1">
<ns1:Geometry>
UwFrRdIvZZdLf4MAcEb+EkvXyRWoALENRv6uHoGfrQHgZ8i8VQc5AA==</ns1:RouteID>
</ns1:Geometry>
<ns1:Buffer uom="KM" value="1.0"/>
<ns1:Properties>
<ns1:Property name="device_c2" value="2000"/>
</ns1:Properties>
</ns1:Route>
<ns1:Route metaInfo="metaInfo" id="9" name="name6"
description="description1">
<ns1:Geometry>
UwFrRdIvZZdLf4MAcEb+EkvXyRWoALENRv6uHoGfrQHgZ8i8VQc5AA==</ns1:RouteID>
</ns1:Geometry>
5-29
October 15, 2010
<ns1:Buffer uom="KM" value="1.0"/>
<ns1:Properties>
</ns1:Properties>
</ns1:Route>
</ns1:RouteRetrieveResponse>
5.4.2.1.5 ComplianceCheckResponse
For the number of points requested in a route compliance check,
ComplianceCheckResponse returns the same number of Checkpoint
violation values. When a point is determined to violate the route compliance,
CheckPoint violated="true" is returned. When a point is determined not to
violate the route compliance, CheckPoint violated="false" is returned. These
violations for each point are returned in the response in the order as the points were
ordered in the request. From the following ComplianceCheckRequest:
<ns1:ComplianceCheckRequest>
<ns1:CheckPoint>
<gml:pos xmlns:gml="http://www.opengis.net/gml">35.80667
80.88838</gml:pos>
</ns1:CheckPoint>
<ns1:CheckPoint>
80.88838</gml:pos>
</ns1:CheckPoint>
<ns1:CheckPoint>
81.25517</gml:pos>
</ns1:CheckPoint>
<ns1:CheckPoint>
80.88838</gml:pos>
</ns1:CheckPoint>
<ns1:ComplianceLookupCriteria>
<ns1:ID>5</ns1:ID>
</ns1:ComplianceLookupCriteria>
</ns1:ComplianceCheckRequest>
-
-
-
-
the response is as follows:
<ns1:RouteComplianceResponse>
<ns1:ComplianceCheckResponse>
<ns1:CheckPoint violated="true"
5-30
pointIndex="0"/>
pointIndex="1"/>
pointIndex="2"/>
pointIndex="3"/>
October 15, 2010
</ns1:ComplianceCheckResponse>
</ns1:RouteComplianceResponse>
5-31
October 15, 2010
5-32

Read Docs

Transcription

Similar documents

dental fear? - Sedation Dentist Ocean City

DDS profile - Digital Document Services

Progress Newsletter Volume 3 Number 1

Mise en page 1

TLC-Dec15-Ronit-3

Four Kernels

ProgressNEWSLETTER

Proposed Xpress Route 423 Schedule, Fare, and Route: