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 deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 . . . . . . . . . . . . . . . . . . . . . . . DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 deCarta Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 deCarta Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="(300 - 398), (301 - 399)"/> <ns1:Street>2nd Ave</ns1:Street> </ns1:StreetAddress> <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 ); DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. xv October 15, 2010 xvi DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 1-5 October 15, 2010 Architecture of Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 1-7 October 15, 2010 Architecture of Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 Calculates distance and ETA to determine best vehicle for job using traffic data in calculating distance and ETA. Dispatch04.java Dispatch04.xml Calculates distance and ETA to determine best vehicle 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 1-11 October 15, 2010 Documentation and Examples Table 1.2. Sample Java Code and XML Example Requests (Continued) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. Introduction October 15, 2010 Table 1.2. Sample Java Code and XML Example Requests (Continued) 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 1-13 October 15, 2010 Documentation and Examples Table 1.2. Sample Java Code and XML Example Requests (Continued) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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! DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-11 October 15, 2010 Features of the Dev Zone Table 2.1. Partial List of Configurations with Sample Map Images (Continued) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. The Developer Zone October 15, 2010 Table 2.1. Partial List of Configurations with Sample Map Images (Continued) 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-13 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-15 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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: DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-17 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-19 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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: DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-21 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-23 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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: DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-25 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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). DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 2-27 October 15, 2010 Features of the Dev Zone 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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"; DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-7 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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: DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-9 October 15, 2010 Self-hosted DDS Web Services <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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> <param-value>8</param-value> <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> <param-value>17</param-value> <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> <param-value>70</param-value> <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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-11 October 15, 2010 Self-hosted DDS Web Services </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> <param-value>8080</param-value> <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-13 October 15, 2010 Self-hosted DDS Web Services 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"> - <!-- Use cloneable-client to minimize repetition --> - <cloneable-client name="default-client" role="ws-client"> 3-14 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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> - <!-- Assign clientName and clientPassword by cloning a cloneable-client --> - <!-- All configurations from the cloneable client are cloned into this client-clone --> <client-clone password="abc123" name="someclient" cloneOf="default-client" /> - <!-- client with admin role is requird to log into certain tabs of web based console --> - <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> - <!-- Add additional configurations as needed. This configuration demonstrates online --> - <!-- image settings. The us-carto-nt image settings require navteq data, and are --> - <!-- documented in docs/USCartographicNT_ImageSettingConfiguration_DDS413.pdf --> - <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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-15 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-17 October 15, 2010 Self-hosted DDS Web Services [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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-19 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-21 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-23 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-25 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-27 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-29 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-31 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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: DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-33 October 15, 2010 Self-hosted DDS Web Services 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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: DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-35 October 15, 2010 Self-hosted DDS Web Services Click the Start Rendering button, and the rendering begins. The display shows a running status: 3-36 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 3-37 October 15, 2010 3-38 Self-hosted DDS Web Services DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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). DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. Directory01.xml example request Directory01.xml example response <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <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: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:XLS> <ns1:ResponseHeader sessionID="999"/> <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:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="(300 - 398), (301 - 399)"/> <ns1:Street>2nd Ave</ns1:Street> </ns1:StreetAddress> <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> </ns1:XLS> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-5 October 15, 2010 Requests and Responses 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: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns1:XLS ns1:lang="en" version="1" xmlns:ns1="http://www.opengis.net/ xls"> ... </ns1:XLS> 4-6 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. The following example is from the XML sample code in Directory01.xml: <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. The following example is from the XML sample code in Directory01.xml: 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-7 October 15, 2010 Requests and Responses The following example is from the XML sample code in Directory01.xml: 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="100"/> <ns1:Street>First Ave.</ns1:Street> </ns1:StreetAddress> <ns1:PostalCode>11111</ns1:PostalCode> </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) The following example is from the XML sample code in Directory01.xml: methodName="DirectoryRequest" DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-9 October 15, 2010 Requests and Responses 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. The following example is from the XML sample code in Directory01.xml: 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. The following example is from the XML sample code in Directory01.xml: 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. 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:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="(300 - 398), (301 - 399)"/> <ns1:Street>2nd Ave</ns1:Street> </ns1:StreetAddress> <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> 4.3.1 Requests The following sections provide some additional explanation of the main elements shown in the example Directory Service request. 4-12 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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" maximumResponses="25" version="1.0"> ... </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: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> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-13 October 15, 2010 Directory Service (POI Lookups) 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"/> </ns1:POIProperties> 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"/> </ns1:POIProperties> 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"/> </ns1:POIProperties> 4-14 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-15 October 15, 2010 Directory Service (POI Lookups) 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 The following sections provide some additional explanation of the main elements 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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:Point xmlns:ns2="http://www.opengis.net/gml"> <ns2:pos>41.0015 -72.003</ns2:pos> </ns2:Point> <ns1:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="(200 - 298), (201 - 299)"/> <ns1:Street>1st St</ns1:Street> </ns1:StreetAddress> <ns1:Place type="CountrySubdivision">NY</ns1:Place> <ns1:Place type="Municipality">NEW YORK</ns1:Place> <ns1:PostalCode>11111</ns1:PostalCode> </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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-17 October 15, 2010 Directory Service (POI Lookups) 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:XLS ns1:lang="en" version="1" xmlns:ns1="http://www.opengis.net/xls"> <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:POIProperties> </ns1:DirectoryRequest> </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 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns1:XLS ns1:lang="en" rel="4.1.3sp02" version="1.0" xmlns:ns1="http://www.opengis.net/xls"> <ns1:ResponseHeader sessionID="999"/> <ns1:Response version="1.0" numberOfResponses="0" requestID="10"> <ns1:DirectoryResponse> <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:Point xmlns:ns2="http://www.opengis.net/gml"> <ns2:pos>41.003 -72.004</ns2:pos> </ns2:Point> 4-18 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 <ns1:Address countryCode="US"> <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:Point xmlns:ns3="http://www.opengis.net/gml"> <ns3:pos>41.0029 -72.0021</ns3:pos> </ns3:Point> <ns1:Address countryCode="US"> <ns1:freeFormAddress>100 2nd St, Stickville, 11111</ns1:freeFormAddress> </ns1:Address> </ns1:POI> <ns1:Distance uom="M" value="42.31"/> </ns1:POIContext> </ns1:DirectoryResponse> </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"> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-19 October 15, 2010 Directory Service (POI Lookups) - <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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"/> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-21 October 15, 2010 Directory Service (POI Lookups) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 4.4 Location Utility Service (Geocoding and Reverse Geocoding) The xml version, XLS, RequestHeader, and ResponseHeader elements of 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 Requests and Responses” on page 4-4. Figure 4.5 shows the main sub-elements of the 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" maximumResponses="25" version="1.0"> <ns1:GeocodeRequest> <ns1:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="100"/> <ns1:Street>First Ave.</ns1:Street> </ns1:StreetAddress> <ns1:PostalCode>11111</ns1:PostalCode> </ns1:Address> </ns1:GeocodeRequest> </ns1:Request> <ns1:Response version="1.0" requestID="10" numberOfResponses="1"> <ns1:GeocodeResponse> <ns1:GeocodeResponseList numberOfGeocodedAddresses="1"> <ns1:GeocodedAddress> <ns2:Point xmlns:ns2="http://www.opengis.net/gml"> <ns2:pos>41.003 -72.002896</ns2:pos> </ns2:Point> <ns1:Address countryCode="US"> <ns1:StreetAddress> <ns1:Building number="100"/> <ns1:Street>1st Ave</ns1:Street> </ns1:StreetAddress> <ns1:Place type="CountrySubdivision">NY</ns1:Place> <ns1:Place type="CountrySecondarySubdivision">SUFFOLK</ ns1:Place> <ns1:Place type="Municipality">NEW YORK</ns1:Place> <ns1:PostalCode>11111</ns1:PostalCode> </ns1:Address> <ns1:GeocodeMatchCode matchType="PATTERN MATCH" accuracy="1.0"/> </ns1:GeocodedAddress> </ns1:GeocodeResponseList> </ns1:GeocodeResponse> </ns1:Response> 4.4.1 Requests The following sections provide some additional explanation of the main elements 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 The following sections provide some additional explanation of the main elements 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-25 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 accuracy score gives the pattern match confidence. 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 accuracy score gives the pattern match confidence. 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-27 October 15, 2010 Location Utility Service (Geocoding and Reverse Table 4.2. Descriptions of Values for GeocodeMatchCode 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 This matchType generally indicates a very poor 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 This matchType generally indicates a very poor 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 Table 4.2. Descriptions of Values for GeocodeMatchCode 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-29 October 15, 2010 Location Utility Service (Geocoding and Reverse Table 4.2. Descriptions of Values for GeocodeMatchCode 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 Table 4.2. Descriptions of Values for GeocodeMatchCode 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-31 October 15, 2010 Location Utility Service (Geocoding and Reverse 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. 4.4.3 deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-33 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-35 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-37 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-39 October 15, 2010 Location Utility Service (Geocoding and Reverse 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="G4" if-input-contains="G4">${G4}</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> <Control name="QG4" if-input-contains="G4">PAT,90</Control> <NextState if-status=".*not found in geography">SimpleDemo.StreetAddress.adjacency01</NextState> <NextState>SimpleDemo.StreetAddress.aggressivePatternMatch</ NextState> </State> <State name="aggressivePatternMatch"> <Control name="QSN">PAT,65</Control> <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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="LL"/> <Control name="VR"/> </Remove> <NextState querytoken="LGEO">SimpleDemo.Geography.$RESUME_STATE</NextState> <!-- streetAddress state machine final exit point. Enter Geography state machine--> </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"> <Input name="G0">${G0}</Input> <Input name="G1" if-input-contains="G1">${G1}</Input> <Input name="G2" if-input-contains="G2">${G2}</Input> <Input name="G4" if-input-contains="G4">${G4}</Input> <Control name="Utrace2"/> <Control name="UGEOCODE_TACTIC">GEOGRAPHY PATTERN MATCH</ Control> <Control name="LL"/> <Control name="LLMIN"/> <Control name="LLMAX"/> <Control name="G0"/> <Control name="G1"/> <Control name="QG1" if-input-contains="G1">PAT,80</Control> <Control name="G2" if-input-contains="G2|G4|G5"/> <Control name="QG2" if-input-contains="G2">PAT,90</Control> <Control name="G4" if-input-contains="G4|G5"/> <Control name="QG4" if-input-contains="G4">PAT,90</Control> <NextState DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-41 October 15, 2010 Location Utility Service (Geocoding and Reverse 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> <Control name="QG1" if-input-contains="G1">PAT,75</Control> <Control name="QG2" if-input-contains="G2">PAT,65</Control> <Control name="QG4" if-input-contains="G4">PAT,65</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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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|| ********************************************************************** DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-43 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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: <Input name="G0">${G0}</Input> <Input name="G1" if-input-contains="G1">${G1}</Input> <Control name="UGEOCODE_TACTIC">PATTERN MATCH</Control> <Control name="QSN">PAT,90</Control> <Control name="LL"/> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-45 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 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 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 MATCH%QSN=PAT,65%LL%GZ%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARAC TERENCODING=iso-8859-1|| ********************************************************************** ********************************************************************** ** DDS RESPONSE B-2 ** LADR|%EXTIME=219%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME PATTERN MATCH%N=2%S=OK|%G0=USA%G1=CA%G2=SANTA CLARA%G4=SUNNYVALE%G6=94086%PG=100%SN=GRAND FIR 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 Discussion of the results: 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-47 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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="QSN">PAT,65</Control> <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 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 C-1 ** LADR|%EXTIME=562%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Street name not 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-49 October 15, 2010 Location Utility Service (Geocoding and Reverse 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 CLARA%G4=SUNNYVALE%G6=94086%PG=0%SN=GRAND FIR AVE%PSN=100%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305|| ********************************************************************** Discussion of the results: 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: <NextState if-status=".*not found in geography"> SimpleDemo.StreetAddress.adjacency01</NextState> 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 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|| 4-50 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 ********************************************************************** ********************************************************************** ** DDS RESPONSE D-1 ** LADR|%EXTIME=78%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Geography not found|| ********************************************************************** ********************************************************************** ** DDS QUERY D-2 ** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand fir ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=GEOGRAPHY PATTERN MATCH%QSN=PAT,90%LL%GZ%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARAC 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 ** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand fir ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY PATTERN MATCH%QSN=PAT,90%LL%GZ%QG1=PAT,75%QG4=PAT,65%S%M=3%EXTIME%DS=NT%CHARAC TERENCODING=iso-8859-1%Utrace2%LLMIN%LLMAX%G0%G1%G2%G4|| ********************************************************************** *** ********************************************************************** ** DDS RESPONSE D-3 ** LADR|%EXTIME=78%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY PATTERN MATCH%N=1%S=OK%Utrace2=|%G0=USA%G1=CA%G2=SANTA CLARA%G4=SUNNYVALE%G6=94086%PG=85%SN=GRAND FIR AVE%PSN=100%VR=2,3736622,-12202145,81,29%AR=620 - 600%LL=37.366625,122.021305|| ********************************************************************** Discussion of the results: 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-51 October 15, 2010 Location Utility Service (Geocoding and Reverse 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: <Control name="QG1" if-input-contains="G1">PAT,75</Control> <Control name="QG2" if-input-contains="G2">PAT,65</Control> <Control name="QG4" if-input-contains="G4">PAT,65</Control> 4-52 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 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 E-1 ** LADR|%EXTIME=62%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Geography not found|| ********************************************************************** ********************************************************************** ** DDS QUERY E-2 ** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=GEOGRAPHY PATTERN MATCH%QSN=PAT,90%LL%GZ%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARAC TERENCODING=iso-8859-1%Utrace2%LLMIN%LLMAX%G0%G1%G2%G4|| ********************************************************************** ********************************************************************** ** DDS RESPONSE E-2 ** LADR|%EXTIME=47%UGEOCODE_TACTIC=GEOGRAPHY PATTERN MATCH%N=0%S=Geography not found%Utrace2=|| ********************************************************************** ********************************************************************** ** DDS QUERY E-3 ** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE GEOGRAPHY DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-53 October 15, 2010 Location Utility Service (Geocoding and Reverse PATTERN MATCH%QSN=PAT,90%LL%GZ%QG1=PAT,75%QG4=PAT,65%S%M=3%EXTIME%DS=NT%CHARAC TERENCODING=iso-8859-1%Utrace2%LLMIN%LLMAX%G0%G1%G2%G4|| ********************************************************************** ********************************************************************** ** 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 ** LADR|%G0=USA%G1=CA%G4=sunval%SN=grand fur%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME PATTERN MATCH%QSN=PAT,65%LL%GZ%QG1=PAT,75%QG4=PAT,65%S%M=3%EXTIME%DS=NT%CHARAC TERENCODING=iso-8859-1%Utrace2%LLMIN%LLMAX%G0%G1%G2%G4|| ********************************************************************** ********************************************************************** ** DDS RESPONSE E-4 ** LADR|%EXTIME=62%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME PATTERN MATCH%N=2%S=OK%Utrace2=|%G0=USA%G1=CA%G2=SANTA CLARA%G4=SUNNYVALE%G6=94086%PG=85%SN=GRAND FIR 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|| ********************************************************************** Discussion of the results: 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 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 F-1 ** LADR|%EXTIME=78%UGEOCODE_TACTIC=PATTERN MATCH%N=0%S=Street name not found|| ********************************************************************** ********************************************************************** ** DDS QUERY F-2 ** LADR|%G0=USA%G1=CA%G4=sunnyvale%SN=bjkdslkdiufifej ave%NO=610%CUST=someclient|%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME PATTERN MATCH%QSN=PAT,65%LL%GZ%QG1=PAT,80%QG4=PAT,90%S%M=3%EXTIME%DS=NT%CHARAC TERENCODING=iso-8859-1|| ********************************************************************** ********************************************************************** ** DDS RESPONSE F-2 ** LADR|%EXTIME=62%UGEOCODE_TACTIC=AGGRESSIVE STREETNAME PATTERN 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-55 October 15, 2010 Location Utility Service (Geocoding and Reverse CLARA%G4=SUNNYVALE%PG=100%LLMIN=37.254639,122.156982%LLMAX=37.433165,-121.923524|| ********************************************************************** Discussion of the results: 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 if-status=".*not found in geography"> SimpleDemo.StreetAddress.adjacency01</NextState> <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="LL"/> <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 4.5 Presentation Service (Drawing Maps) The xml version, XLS, RequestHeader, and ResponseHeader elements of Presentation 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.9. The Request/Response Elements of Presentation Service Map01.xml example request Map01.xml example response <ns1:Request methodName="PortrayMapRequest" requestID="10" maximumResponses="25" version="1.0"> <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:Response version="1.0" requestID="10" numberOfResponses="1"> <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: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:Map> </ns1:PortrayMapResponse> </ns1:Response> 4.5.1 Requests The following sections provide some additional explanation of the main elements shown in the example Presentation Service request. 4.5.1.1 methodName The value of methodName is PortrayMapRequest in requests to draw a map. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 The following sections provide some additional explanation of the main elements 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. 4.5.3 deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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”. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-59 October 15, 2010 Presentation Service (Drawing Maps) 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 <?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 clientPassword="XXX" configuration="blue-steel" sessionID="999" clientName="XXX"/> <ns1:Request requestID="10" methodName="PortrayMapRequest" maximumResponses="25" version="1.0"> <ns1: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:PortrayMapRequest> </ns1:Request> </ns1:XLS> <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns1:XLS ns1:lang="en" version="1" xmlns:ns1="http://www.opengis.net/xls"> <ns1:ResponseHeader sessionID="999"/> <ns1:Response version="1.0" requestID="10" numberOfResponses="1"> <ns1:PortrayMapResponse> <ns1:Map> <ns1:Content height="500" format="GIF" width="500"> <ns1:URL>http://ws.decarta.com:8080/openls/image/2124343908.gif</ns1:URL> </ns1:Content> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131 -121.9981</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1</ns1:Radius> </ns1:CenterContext> </ns1:Map> <ns1:GeocodeResponseList numberOfGeocodedAddresses="1"> <ns1:GeocodedAddress> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <ns3:pos>37.355131 -121.9981</ns3:pos> </ns3:Point> <ns1:Address countryCode="US"> <ns1:freeFormAddress>1760 HALFORD AVE, SANTA CLARA, CA 95051</ns1:freeFormAddress> </ns1:Address> <ns1:GeocodeMatchCode matchType="PATTERN MATCH" accuracy="1.0"/> </ns1:GeocodedAddress> </ns1:GeocodeResponseList> </ns1:PortrayMapResponse> </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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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"/> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-61 October 15, 2010 Presentation Service (Drawing Maps) <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:Output width="500" height="500"> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131 -121.9981</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1</ns1:Radius> </ns1:CenterContext> </ns1:Output> <ns1:Overlay> <ns1:Position> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <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:PortrayMapRequest> <ns1:PortrayMapResponse> <ns1:Map> <ns1:Content height="500" format="GIF" width="500"> <ns1:URL>http://ws.decarta.com:8080/openls/image/572122358.gif</ns1:URL> </ns1:Content> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131 -121.98677858467161</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1.000000000000153snip</ns1:Radius> </ns1:CenterContext> </ns1:Map> </ns1:PortrayMapResponse> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-63 October 15, 2010 Presentation Service (Drawing Maps) Like pan, zoom is an attribute of the PortrayMapRequest element. Here is an example: <ns1:PortrayMapRequest zoom="0.4"> 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:PortrayMapRequest zoom="0.4"> <ns1:Output width="500" height="500"> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131 -121.98677858467161</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1.0000000000001534328snip5</ ns1:Radius> </ns1:CenterContext> </ns1:Output> <ns1:Overlay> <ns1:Position> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <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:PortrayMapRequest> <ns1:PortrayMapResponse> <ns1:Map> <ns1:Content height="500" format="GIF" width="500"> <ns1:URL>http://ws.decarta.com:8080/openls/image/928762713.gif</ns1:URL> </ns1:Content> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131 -121.98677858467161</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1.400000005960484683598snip</ ns1:Radius> </ns1:CenterContext> </ns1:Map> </ns1:PortrayMapResponse> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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:PortrayMapRequest zoom="0.0"> <ns1:ScreenCoordinate y="438" x="177"/> <ns1:Output width="500" height="500"> ...> </ns1:Output> ... </ns1:PortrayMapRequest> 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-65 October 15, 2010 Presentation Service (Drawing Maps) 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:PortrayMapRequest zoom="0.0"> <ns1:ScreenCoordinate y="438" x="177"/> <ns1:Output width="500" height="500"> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.355131 121.98677858467161</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1.400000005960484683598110677849035710096359252929687 5</ns1:Radius> </ns1:CenterContext> </ns1:Output> <ns1:Overlay> <ns1:Position> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <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:PortrayMapRequest> <ns1:PortrayMapResponse> <ns1:Map> <ns1:Content height="500" format="GIF" width="500"> <ns1:URL>http://ws.decarta.com:8080/openls/image/2046455293.gif</ns1:URL> </ns1:Content> <ns1:CenterContext SRS="WGS-84"> <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:CenterContext> </ns1:Map> </ns1:PortrayMapResponse> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-67 October 15, 2010 Presentation Service (Drawing Maps) 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" maximumResponses="25" version="1.0"> - <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:Radius unit="KM">0.30</ns1:Radius> </ns1:CenterContext> </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:PortrayMapRequest> </ns1:Request> </ns1:XLS> When using the Stickville dataset, Map14.xml produces the display Figure 4.19: 4-68 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-69 October 15, 2010 Presentation Service (Drawing Maps) 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:PortrayMapRequest> <ns1:Output width="400" height="400"> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">37.34565655823944 -121.99140677920954</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">0.3</ns1:Radius> </ns1:CenterContext> </ns1:Output> <ns1:Overlay> <ns1:Position> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <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:PortrayMapRequest> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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:Output width="400" height="400"> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/ gml">37.34565655823944 -121.99140677920954</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">0.3</ns1:Radius> </ns1:CenterContext> </ns1:Output> <ns1:Overlay> <ns1:Position> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <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:PortrayMapRequest> <ns1:PortrayMapResponse> <ns1:Map> <ns1:Content height="400" format="GIF" width="400"> <ns1:URL>http://ws.decarta.com:8080/openls/image/1111643085.gif</ ns1:URL> </ns1:Content> <ns1:CenterContext SRS="WGS-84"> <ns1:CenterPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/ gml">37.34904388711108 -121.9930553916076</ns2:pos> </ns1:CenterPoint> <ns1:Radius unit="KM">1.0124935432863snip</ns1:Radius> </ns1:CenterContext> </ns1:Map> </ns1:PortrayMapResponse> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-71 October 15, 2010 Presentation Service (Drawing Maps) 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:PortrayMapRequest> <ns1:Output format="JPG" height="400" width="400"> <ns1:CenterAddress> <ns1:Address countryCode="US"> <ns1:freeFormAddress>300 Second Ave, 11111</ns1:freeFormAddress> </ns1:Address> </ns1:CenterAddress> <ns1:jpg-parameters quality="80" subsampling="2x2"/> </ns1:Output> </ns1:PortrayMapRequest> 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-73 October 15, 2010 Route Service (Calculate Routes) 4.6 Route Service (Calculate Routes) The xml version, XLS, RequestHeader, and ResponseHeader elements of Route 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.26. The Request/Response Elements of Route Service Route01.xml example request Route01.xml example response <ns1:Request methodName="DetermineRouteRequest" requestID="10" maximumResponses="25" version="1.0"> <ns1:DetermineRouteRequest provideRouteHandle="false"> <ns1:RoutePlan> <ns1:RoutePreference>Fastest</ns1:RoutePreference> <ns1:WayPointList> <ns1:StartPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>1 First St., Stickville, NY 11111</ ns1:freeFormAddress> </ns1:Address> </ns1:StartPoint> <ns1:EndPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>399 3rd ave, Stickville, NY 11111</ ns1:freeFormAddress> </ns1:Address> </ns1:EndPoint> </ns1:WayPointList> </ns1:RoutePlan> <ns1:RouteInstructionsRequest/> </ns1:DetermineRouteRequest> </ns1:Request> <ns1:Response version="1.0" requestID="10" numberOfResponses="1"> <ns1:DetermineRouteResponse> <ns1:StartAddressCandidates numberOfGeocodedAddresses="1"> <ns1:GeocodedAddress> <ns2:Point xmlns:ns2="http://www.opengis.net/gml"> <ns2:pos>41.003901 -72.003</ns2:pos> </ns2:Point> <ns1:Address countryCode="US"> <ns1:freeFormAddress>1 1st St, NEW YORK, NY 11111</ ns1:freeFormAddress> </ns1:Address> <ns1:GeocodeMatchCode matchType="PATTERN MATCH" accuracy="1.0"/> </ns1:GeocodedAddress> </ns1:StartAddressCandidates> <ns1:EndAddressCandidates numberOfGeocodedAddresses="1"> <ns1:GeocodedAddress> ... </ns1:GeocodedAddress> </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> <ns5:pos xmlns:ns5="http://www.opengis.net/gml">41.0039 72.00011</ns5: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" duration="P0DT0H0M35S"> ... </ns1:RouteInstruction> </ns1:RouteInstructionsList> </ns1:DetermineRouteResponse> </ns1:Response> 4-74 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 4.6.1 Requests The following sections provide some additional explanation of the main elements 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-75 October 15, 2010 Route Service (Calculate Routes) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 The following sections provide some additional explanation of the main elements 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-77 October 15, 2010 Route Service (Calculate Routes) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 4.6.3 deCarta Extensions 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-79 October 15, 2010 Route Service (Calculate Routes) 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"> <ns1:GeocodedAddress> <ns2:Point xmlns:ns2="http://www.opengis.net/gml"> <ns2:pos>37.336776 -121.889585</ns2:pos> </ns2:Point> <ns1:Address countryCode="US"> <ns1:freeFormAddress>4 N 2ND ST, SAN JOSE, CA 95113</ ns1:freeFormAddress> </ns1:Address> <ns1:GeocodeMatchCode matchType="PATTERN MATCH" accuracy="0.93"/> </ns1:GeocodedAddress> <ns1:GeocodedAddress> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <ns3:pos>37.336559 -121.889426</ns3:pos> </ns3:Point> <ns1:Address countryCode="US"> <ns1:freeFormAddress>4 S 2ND ST, SAN JOSE, CA 95113</ ns1:freeFormAddress> </ns1:Address> <ns1:GeocodeMatchCode matchType="PATTERN MATCH" accuracy="0.93"/> </ns1:GeocodedAddress> </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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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:DetermineRouteRequest provideRouteHandle="false"> <ns1:RoutePlan> <ns1:RoutePreference>Fastest</ns1:RoutePreference> <ns1:WayPointList> <ns1:StartPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>1 First St., Stickville, NY 11111</ ns1:freeFormAddress> </ns1:Address> </ns1:StartPoint> <ns1:EndPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>399 3rd ave, Stickville, NY 11111</ ns1:freeFormAddress> </ns1:Address> </ns1:EndPoint> </ns1:WayPointList> </ns1:RoutePlan> <ns1:RouteInstructionsRequest/> <ns1:RouteGeometryRequest/> <ns1:RouteMapRequest> <ns1:Output style="Overview" width="500" height="500"/> <ns1:Output style="Maneuver" width="200" height="200"/> </ns1:RouteMapRequest> </ns1:DetermineRouteRequest> <ns1:RouteMap description="Route Overview"> <ns1:Content height="500" format="GIF" width="500"> <ns1:URL>http://ws.decarta.com:8080/openls/image/1693873727.gif</ ns1:URL> </ns1:Content> ... </ns1:RouteMap> <ns1:RouteMap description="route maneuver 1"> <ns1:Content height="200" format="GIF" width="200"> <ns1:URL>http://ws.decarta.com:8080/openls/image/1226448269.gif</ ns1:URL> </ns1:Content> ... </ns1:RouteMap> <ns1:RouteMap description="route maneuver 2"> <ns1:Content height="200" format="GIF" width="200"> <ns1:URL>http://ws.decarta.com:8080/openls/image/298940379.gif</ ns1:URL> </ns1:Content> ... </ns1:RouteMap> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-81 October 15, 2010 Route Service (Calculate Routes) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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“. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-83 October 15, 2010 Route Service (Calculate Routes) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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:RoutePreference>Fastest</ns1:RoutePreference> <ns1:WayPointList> <ns1:StartPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>1 First St.,11111</ns1:freeFormAddress> </ns1:Address> </ns1:StartPoint> <ns1:EndPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>399 3rd ave, 11111</ns1:freeFormAddress> </ns1:Address> </ns1:EndPoint> </ns1:WayPointList> </ns1:RoutePlan> <ns1:RouteInstructionsRequest rules="maneuver-rules"/> </ns1:DetermineRouteRequest> </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' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 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> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-85 October 15, 2010 Route Service (Calculate Routes) <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 <route-instructions xmlns='http://decarta.com/dds/ws/routeInstructions' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://decarta.com/dds/ws/routeInstructions file:/C:/project/webservices/schema/RouteInstructions.xsd'> <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> <departure-maneuver> <instruction>Begin on ${current-road} heading ${OHED} towards ${next-road}. </instruction> </departure-maneuver> <arrival-maneuver> <instruction>Arrive at destination</instruction> </arrival-maneuver> <maneuver id="turn"> <instruction>$TURN-ANGLE{TANG} onto ${next-road}.</instruction> </maneuver> </route-instructions> These rules produce instructions that include the direction in which the driver should turn (note highlighting in yellow below). Figure 4.35. Driving Directions Results from example-rules-02.xml 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-87 October 15, 2010 Route Service (Calculate Routes) 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 <route-instructions xmlns='http://decarta.com/dds/ws/routeInstructions' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://decarta.com/dds/ws/routeInstructions file:/C:/project/webservices/schema/RouteInstructions.xsd'> <translations> <translate from="^R$" to="Miles"/> </translations> <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> <departure-maneuver> <instruction>Begin on ${current-road} heading ${OHED} towards ${next-road}. </instruction> </departure-maneuver> <arrival-maneuver> <instruction>Arrive at destination</instruction> </arrival-maneuver> <maneuver id="turn"> <instruction>Drive for ${DIST.VAL} $TRANSLATE{DIST.UOM}. Turn $TURN-ANGLE{TANG} onto ${next-road}. </instruction> </maneuver> </route-instructions> Figure 4.37. Driving Directions Results from example-rules-03.xml 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions 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 <route-instructions xmlns='http://decarta.com/dds/ws/routeInstructions' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://decarta.com/dds/ws/routeInstructions file:/C:/project/webservices/schema/RouteInstructions.xsd'> <translations> <translate from="^R$" to="Miles"/> </translations> <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> <departure-maneuver> <instruction>Begin on ${current-road} heading ${OHED} towards ${next-road}. </instruction> </departure-maneuver> <arrival-maneuver> <instruction>Arrive at destination</instruction> </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> <maneuver id="turn"> <instruction>Drive for ${DIST.VAL} $TRANSLATE{DIST.UOM}. Turn $TURN-ANGLE{TANG} onto ${next-road}. </instruction> </maneuver> </route-instructions> The ignore element controls whether or not an RMAN output group is ignored. All ignore elements are processed before maneuver elements are processed. An DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 4-89 October 15, 2010 Route Service (Calculate Routes) 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Core Services and deCarta Extensions October 15, 2010 4.7 Scrolling Service The xml version, XLS, RequestHeader, and ResponseHeader elements of Scrolling 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.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="CountrySubdivision">NY</ns1:Place> <ns1:Place type="Municipality">New York</ns1:Place> </ns1:ScrollRequest> </ns1:Request> <ns1:Response version="1.0" requestID="1" numberOfResponses="10"> <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> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">40.56971 74.14439</ns2:pos> <ns3:pos xmlns:ns3="http://www.opengis.net/gml">40.85554 73.82853</ns3:pos> </ns1:BoundingBox> </ns1:ScrollResponse> </ns1:Response> 4.7.1 Request The following sections provide some additional explanation of the main elements shown in the example Scrolling Service request. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. CHAPTER 5 OpenLS Fleet Services 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-1 October 15, 2010 Dispatch Service 5.1 Dispatch Service The xml version, XLS, RequestHeader, and ResponseHeader elements of Dispatch 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. 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:RoutePreference>Fastest</ns1:RoutePreference> <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:Point xmlns:ns2="http://www.opengis.net/gml"> <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:Vehicle ID="7654322"> <ns1:Position> <ns3:Point xmlns:ns3="http://www.opengis.net/gml"> <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:Vehicle ID="7654323"> <ns1:Position> <ns4:Point xmlns:ns4="http://www.opengis.net/gml"> <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> <?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:ResponseHeader sessionID="-"/> <ns1:Response requestID="10" version="1.0" numberOfResponses="0"> <ns1:DispatchResponse> <ns1:BestVehicleForJobResponse> <ns1:Vehicle ID="7654321"> <ns1:Position> <ns2:Point xmlns:ns2="http://www.opengis.net/gml"> <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:Distance uom="MI" value="33.74"/> <ns1:Eta>4140</ns1:Eta> </ns1:Route> <ns1:RouteInstructionsList ns1:lang="english"> <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> </ns1:RouteInstructionsList> </ns1:BestVehicleForJobResponse> </ns1:DispatchResponse> <ns1:RouteInstruction description="route maneuver 7" tour="0" duration="P0DT0H5M6S"> <ns1:Instruction>Turn sharp right onto PINE PLAIN RD/SC-65 .1:Instruction> <ns1:distance uom="MI" value="4.24"/> </ns1:RouteInstruction> 5-2 </ns1:RouteInstructionsList> </ns1:BestVehicleForJobResponse> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 5.1.1 Requests The following sections provide some additional explanation of the main elements 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:RoutePreference>Fastest</ns1:RoutePreference> <ns1:BestJobForVehicleRequest order="TIME" returnManeuver="true"> <ns1:JobList> <ns1:Job ID="1234567"> <ns1:Position>33.640237 -81.254883</ns1:Position> <ns1:Schedule>2010-03-20T11:57:38.828+08:00</ns1:Schedule> </ns1:Job> <ns1:Job ID="1234568"> <ns1:Position>33.650237 -81.254883</ns1:Position> <ns1:Schedule>2010-03-20T11:57:38.828+08:00</ns1:Schedule> </ns1:Job> <ns1:Job ID="1234569"> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-3 October 15, 2010 Dispatch Service <ns1:Position>33.660237 -81.254883</ns1:Position> <ns1:Schedule>2010-03-20T11:57:38.828+08:00</ns1:Schedule> </ns1:Job> </ns1:JobList> <ns1:Vehicle ID="7654321"> <ns1:Position> <ns2:Point xmlns:ns2="http://www.opengis.net/gml"> <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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:RoutePreference>Fastest</ns1:RoutePreference> <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 The following sections provide some additional explanation of the main elements shown in the example Dispatch Service response. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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:Position>33.640237 -81.254883</ns1:Position> <ns1:Schedule>2010-03-20T11:57:38.828+08:00</ns1:Schedule> </ns1:Job> <ns1:Route> <ns1:RouteID>jwAAAHhWNBIAAAAAjwAAAF8YClvGeq/YNPBj1BUIQUmX+29RrAJPSvwm/ Kkt8GPUFAAuSgQf+IEsmPUFIgArWgFB/wIOTvwGPUEEUEr9J/ O1IfBj1BMCO0oDoPYFV8Y9QTYFZUr9UADUYeGPUE4DaEr4Kf7jZagBVEb5RFZF+Bjg8QNWSvJE8Ac7pgNJWv7Y892R</ ns1:RouteID> <ns1:Distance uom="MI" value="33.74"/> <ns1:Eta>4140</ns1:Eta> </ns1:Route> <ns1:RouteInstructionsList ns1:lang="english"> <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> <ns1:RouteInstruction description="route maneuver 2" tour="0" duration="P0DT0H9M3S"> <ns1:Instruction>Turn left onto OLD SWAMP RD.</ns1:Instruction> <ns1:distance uom="MI" value="1.72"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 3" tour="0" duration="P0DT0H10M18S"> <ns1:Instruction>Turn sharp right onto OLD STATE RD/OLD SWAMP RD/US-176 .</ns1:Instruction> <ns1:distance uom="MI" value="1.96"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 6" tour="0" duration="P0DT0H5M58S"> <ns1:Instruction>Turn sharp left onto OLD SANDY RUN RD/SC-31 .</ns1:Instruction> <ns1:distance uom="MI" value="3.44"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 7" tour="0" duration="P0DT0H5M6S"> <ns1:Instruction>Turn sharp right onto PINE PLAIN RD/SC-65 .</ns1:Instruction> <ns1:distance uom="MI" value="4.24"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 8" tour="0" duration="P0DT0H0M4S"> <ns1:Instruction>Continue onto MACK ST/SC-65 .</ns1:Instruction> <ns1:distance uom="MI" value="0.07"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 10" tour="0" duration="P0DT0H7M59S"> <ns1:Instruction>Turn left onto SOUTHBOUND RD/S MAIN ST/US-321 .</ns1:Instruction> <ns1:distance uom="MI" value="3.56"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 12" tour="0" duration="P0DT0H2M24S"> <ns1:Instruction>Continue onto SOUTHBOUND RD/US-321 S.</ns1:Instruction> <ns1:distance uom="MI" value="1.11"/> </ns1:RouteInstruction> 5-6 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 <ns1:RouteInstruction description="route maneuver 13" tour="0" duration="P0DT0H3M48S"> <ns1:Instruction>Continue onto SOUTHBOUND RD/US-321 .</ns1:Instruction> <ns1:distance uom="MI" value="3.09"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 19" tour="0" duration="P0DT0H6M8S"> <ns1:Instruction>Bear right onto WHETSTONE RD/SC-3 .</ns1:Instruction> <ns1:distance uom="MI" value="2.65"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 22" tour="0" duration="P0DT0H11M45S"> <ns1:Instruction>Turn right onto HOLLOW CREEK RD.</ns1:Instruction> <ns1:distance uom="MI" value="7.59"/> </ns1:RouteInstruction> <ns1:RouteInstruction description="route maneuver 23" tour="0" duration="P0DT0H6M18S"> <ns1:Instruction>Arrive at destination</ns1:Instruction> <ns1:distance uom="MI" value="4.32"/> </ns1:RouteInstruction> </ns1:RouteInstructionsList> </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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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 level elements of any XLS request and response, as described in “High Level View of Requests and Responses” on page 4-4. Figure 5.3 shows the main sub-elements of the 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" ?> <ns1:XLS ns1:lang="en" version="1.0" xmlns:ns1="http://www.opengis.net/ 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> <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns1:XLS rel="4.5.2.sp02" ns1:lang="en" version="1.0" xmlns:ns1="http:// www.opengis.net/xls"> <ns1:ResponseHeader sessionID="-"/> <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 5.2.1 Requests The following sections provide some additional explanation of the main elements 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-9 October 15, 2010 Exclusion Zone Service Table 5.1. ZoneCreateRequest Examples and File Locations JAVA Sample XML Sample Description ExclusionZone02.java ExclusionZone02.xml Create a CIRCLE exclusion zone ExclusionZone03.java ExclusionZone03.xml Create a LINE exclusion zone ExclusionZone09.java 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"> </ns1:ExclusionZone> 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: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> 5-10 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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:StartTime>11:30:00+00:00</ns1:StartTime> <ns1:EndTime>14:00:00+00:00</ns1:EndTime> </ns1:ActiveTime> </ns1:RestrictedActiveTimes> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-11 October 15, 2010 Exclusion Zone Service 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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.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 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.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"> </ns1:ZoneRetrieveRequest> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-13 October 15, 2010 Exclusion Zone Service 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> </ns1:ZoneRetrieveRequest> 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:Property name="GroupID" value="10"/> </ns1:Properties> </ns1:ZoneRetrieveRequest> 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:DetermineRouteRequest provideRouteHandle="false"> <ns1:RoutePlan useExclusionZone="true"> <ns1:RoutePreference>Fastest</ns1:RoutePreference> <ns1:WayPointList> <ns1:StartPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>1 First St., Stickville, NY 11111</ns1:freeFormAddress> </ns1:Address> </ns1:StartPoint> <ns1:EndPoint> <ns1:Address countryCode="US"> <ns1:freeFormAddress>399 3rd ave, Stickville, NY 11111</ns1:freeFormAddress> </ns1:Address> 5-14 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 </ns1:EndPoint> </ns1:WayPointList> </ns1:RoutePlan> <ns1:RouteInstructionsRequest/> </ns1:DetermineRouteRequest> An example of a DetermineRouteRequest can be found in ExclusionZone10.java or ExclusionZone10.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.2 Responses The following sections provide some additional explanation of the main elements 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:ExclusionZoneResponse> <ns1:ZoneCreateResponse> <ns1:ExclusionZone id="1" description="description of zone01" name="zone01"/> </ns1:ZoneCreateResponse> </ns1:ExclusionZoneResponse> 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-15 October 15, 2010 Exclusion Zone Service 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:ExclusionZoneResponse> <ns1:ZoneUpdateResponse> <ns1:ExclusionZone id="1" description="description of zone01" name="zone01"/> </ns1:ZoneUpdateResponse> </ns1:ExclusionZoneResponse> 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:ExclusionZoneResponse> <ns1:ZoneDeleteResponse> <ns1:ExclusionZone id="1"/> </ns1:ZoneDeleteResponse> </ns1:ExclusionZoneResponse> 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:Property name="createdBy" value="ExclusionZone01"/> <ns1:Property name="GroupID" value="10"/> </ns1:Properties> </ns1:ExclusionZone> <ns1:ExclusionZone id="2" name="zone02" description="description of zone02"> 5-16 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 <ns1:Properties> <ns1:Property name="createdBy" value="ExclusionZone02"/> <ns1:Property name="GroupID" value="10"/> </ns1:Properties> </ns1:ExclusionZone> <ns1:ExclusionZone id="3" name="zone03" description="description of zone03"> <ns1:Properties> <ns1:Property name="createdBy" value="ExclusionZone03"/> <ns1:Property name="GroupID" value="10"/> </ns1:Properties> </ns1:ExclusionZone> </ns1:ZoneRetrieveResponse> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-17 October 15, 2010 Geofencing Service 5.3 Geofencing Service The xml version, XLS, RequestHeader, and ResponseHeader elements of Geofencing 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. 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 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <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:Polygon xmlns:ns2="http://www.opengis.net/gml"> <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:RestrictedActiveTimes> <ns1:ActiveTime recurrenceType="D"> <ns1:StartTime>08:00:00+00:00</ns1:StartTime> <ns1:EndTime>10:00:00+00:00</ns1:EndTime> </ns1:ActiveTime> </ns1:RestrictedActiveTimes> </ns1:Geofence> </ns1:FenceCreateRequest> </ns1:GeofencingRequest> </ns1:Request> </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:ResponseHeader sessionID="-"/> <ns1:Response requestID="10" numberOfResponses="1" version="1.0"> <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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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> </ns2:CircleByCenterPoint> 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, DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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:00+00: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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <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:FenceViolationCheckRequest returnViolationOnly="false"> <ns1:CheckPoint> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">41.0015 -72.0035</ns2:pos> </ns1:CheckPoint> <ns1:CheckPoint> <ns3:pos xmlns:ns3="http://www.opengis.net/gml">41.0015 -72.0025</ns3:pos> </ns1:CheckPoint> </ns1:FenceViolationCheckRequest> </ns1:GeofencingRequest> </ns1:Request> </ns1:XLS> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 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. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <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:FenceRetrieveRequest returnRestrictedActiveTimes="true" returnProperties="true" returnGeometry="true"> <ns1:ID>1</ns1:ID> </ns1:FenceRetrieveRequest> </ns1:GeofencingRequest> </ns1:Request> </ns1:XLS> 5-22 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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:ResponseHeader sessionID="-"/> <ns1:Response requestID="10" numberOfResponses="1" version="1.0"> <ns1:GeofencingResponse> <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> </ns2:CircleByCenterPoint> </ns1:Geometry> <ns1:Properties> <ns1:Property value="Geofencing01" name="createdBy"/> <ns1:Property value="5" name="GroupID"/> </ns1:Properties> <ns1:RestrictedActiveTimes> <ns1:ActiveTime recurrenceType="D" weeklyRecurrenceDay=" "> <ns1:StartTime>08:00:00+00:00</ns1:StartTime> <ns1:EndTime>10:00:00+00:00</ns1:EndTime> </ns1:ActiveTime> </ns1:RestrictedActiveTimes> </ns1:Geofence> </ns1:FenceRetrieveResponse> </ns1:GeofencingResponse> </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: <?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:ResponseHeader sessionID="-"/> <ns1:Response requestID="10" numberOfResponses="3" version="1.0"> <ns1:GeofencingResponse> <ns1:FenceViolationCheckResponse> <ns1:CheckPointResult checkPointIndex="1" isViolation="false"> <ns2:pos xmlns:ns2="http://www.opengis.net/gml">41.0015 -72.0035</ns2:pos> </ns1:CheckPointResult> <ns1:CheckPointResult checkPointIndex="2" isViolation="true"> <ns3:pos xmlns:ns3="http://www.opengis.net/gml">41.0015 -72.0025</ns3:pos> <ns1:ViolatedGeofences> <ns1:Geofence description="description of MyFence01" violationType="I" id="1" name="MyFence01"/> </ns1:ViolatedGeofences> </ns1:CheckPointResult> </ns1:FenceViolationCheckResponse> </ns1:GeofencingResponse> </ns1:Response> </ns1:XLS> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-23 October 15, 2010 Route Compliance Service 5.4 Route Compliance Service The xml version, XLS, RequestHeader, and ResponseHeader elements of Route Compliance 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. 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 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns1:XLS rel="4.5.2" ns1:lang="en" version="1.0" xmlns:ns1="http:// www.opengis.net/xls"> <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> <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns1:XLS rel="4.5.2" ns1:lang="en" version="1" xmlns:ns1="http:// www.opengis.net/xls"> <ns1:ResponseHeader sessionID="-"/> <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 The following sections provide some additional explanation of the main elements in 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-25 October 15, 2010 Route Compliance Service 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"?> <ns1:XLS ns1:lang="en" version="1.0" xmlns:ns1="http://www.opengis.net/ 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" maximumResponses="25" version="1.0"> <ns1:RouteComplianceRequest> 5-26 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 <ns1:RouteRetrieveRequest returnProperty="true" returnGeometry="false"> <!-- whether return properties or geometry, the returnGeometry default is "true" and the returnProperty default is "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, <ns1:RouteID>WgAAAHhWNBIAAAAAWgAAAF8a8CepC3IA7Wbpyl0t/ hAAa0W3OoRn4XS3+ACBW0lTAalvXS3/ 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. DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-27 October 15, 2010 Route Compliance Service 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 following sections provide some additional explanation of the main elements in 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 DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services 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> <ns1:RouteID>WgAAAHhWNBIAAAAAWgAAAF8a8CepC3IA7Wbpyl0t/ hAAa0W3OoRn4XS3+ACBW0lTAalvXS3/ UwFrRdIvZZdLf4MAcEb+EkvXyRWoALENRv6uHoGfrQHgZ8i8VQc5AA==</ns1:RouteID> </ns1:Geometry> <ns1:Buffer uom="KM" value="1.0"/> <ns1:Properties> <ns1:Property name="device_c2" value="2000"/> <ns1:Property name="device_c1" value="1000"/> </ns1:Properties> </ns1:Route> <ns1:Route metaInfo="metaInfo" id="9" name="name6" description="description1"> <ns1:Geometry> <ns1:RouteID>WgAAAHhWNBIAAAAAWgAAAF8a8CepC3IA7Wbpyl0t/ hAAa0W3OoRn4XS3+ACBW0lTAalvXS3/ UwFrRdIvZZdLf4MAcEb+EkvXyRWoALENRv6uHoGfrQHgZ8i8VQc5AA==</ns1:RouteID> </ns1:Geometry> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-29 October 15, 2010 Route Compliance Service <ns1:Buffer uom="KM" value="1.0"/> <ns1:Properties> <ns1:Property name="device_c3" value="3000"/> <ns1:Property name="device_c2" value="2000"/> <ns1:Property name="device_c1" value="1000"/> </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> <gml:pos xmlns:gml="http://www.opengis.net/gml">36.80667 80.88838</gml:pos> </ns1:CheckPoint> <ns1:CheckPoint> <gml:pos xmlns:gml="http://www.opengis.net/gml">33.64062 81.25517</gml:pos> </ns1:CheckPoint> <ns1:CheckPoint> <gml:pos xmlns:gml="http://www.opengis.net/gml">35.80667 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" <ns1:CheckPoint violated="true" <ns1:CheckPoint violated="true" <ns1:CheckPoint violated="true" 5-30 pointIndex="0"/> pointIndex="1"/> pointIndex="2"/> pointIndex="3"/> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. OpenLS Fleet Services October 15, 2010 </ns1:ComplianceCheckResponse> </ns1:RouteComplianceResponse> DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta. 5-31 October 15, 2010 5-32 Route Compliance Service DDS Web Services Application Developer’s Guide deCarta, Inc. Confidential—Do not distribute without written consent from deCarta.