Programming MapPoint in .NET

Preface

Location is everything! Whether you are trying to find driving directions to the airport or looking for a good restaurant in town, location information has become an essential ingredient of our daily life. Enterprises today consider providing location-based services to their customers an important part of their service offerings. Using MapPoint products and services, you can answer questions such as:

• Where am I?

• How do I get from here to there?

• Where is the nearest coffee shop?

Whether you want to answer these questions using an online application, a web service, or a mobile phone in real-time, or offline, this book is for you. MapPoint provides an integrated set of products, servers, and services that helps enterprises improve their customers’ experience by applying mapping and location.

Tip

If you are looking for more programming resources on MapPoint 2004, MP2K Magazine provides excellent online resources and the most up-to-date technical articles on MapPoint 2004 programming. Check it out at http://www.mp2kmag.com.

Who Should Read This Book

Programming MapPoint in .NET will be useful to anyone who wants to develop a location-based application using the following MapPoint technologies:

• MapPoint 2004

• MapPoint Web Service

• Microsoft Location Server

• MSN Virtual Earth

This book provides a jump-start for working with these technologies with in-depth discussions about the core concepts and sample code provided in C#.

What’s in This Book

This book is organized into 4 major sections with a total of 11 chapters. Each product/technology has a dedicated section in the book:

Chapter 1, Hello, MapPoint!

Introduces the MapPoint suite of products and technologies, setting the stage by discussing the basics of each technology and usage scenarios.

Part I, MapPoint 2004

Chapter 2, Programming with MapPoint 2004

Covers programming with the MapPoint 2004 ActiveX control and MapPoint 2004 object model for rendering maps, finding places and addresses, and calculating routes.

Chapter 3, Working with Data in MapPoint 2004

Covers dealing with business data, rendering data maps, and adding thematic shapes using geographic data.

Chapter 4, Advanced MapPoint 2004 Programming

Covers integration with GPS for obtaining real-time location and extending MapPoint capabilities by writing add-ins.

Tip

Future versions of MapPoint (such as MapPoint 2006) are fully backward-compatible with the MapPoint 2004 APIs, so the contents of these chapters are still relevant for MapPoint 2006 and future backward-compatible versions of MapPoint.

Part II, MapPoint Web Service

Chapter 5, Programming MapPoint Web Service

Introduces the basics of programming with MapPoint Web Service.

Chapter 6, MapPoint Web Service Find APIs

Covers creating applications using the Find APIs of the MapPoint Web Service, including techniques for finding places, addresses, and nearby points of interest.

Chapter 7, MapPoint Web Service Route APIs

Covers programming with the Route APIs, such as calculating routes and getting driving directions.

Chapter 8, MapPoint Web Service Render APIs

Covers programming with the Render APIs available with MapPoint Web Service, including rendering maps, routes, LineDrive maps, and polygons.

Part III, MapPoint Location Server

Chapter 9, Programming Microsoft Location Server

Covers the basics of programming with Microsoft Location Server and deployment scenarios.

Chapter 10, Programming with Location Server APIs

Covers programming with the Location Server Web Service to get real-time location using mobile phones; also covers the basics of managing the Location Server, contacts, and privacy settings.

Part IV, MSN Virtual Earth

Chapter 11, Programming with Virtual Earth

Covers the basics of programming with the new MSN Virtual Earth (undocumented) APIs.

Appendixes

Appendix A, Managing Your Data on MapPoint’s Customer Services Site

Provides programming information for the MapPoint Customer Data Service.

Appendix B, Working with Polygons

Provides basic information on understanding polygons in MapPoint Web Service.

Appendix C, Implementing Spatial Search Using SQL Server

Provides a solution for implementing a proximity search within your enterprise network that doesn’t require you to upload your data to MapPoint Web Service.

This book covers the most common application development scenarios with the MapPoint platform. If you feel that something important has been left out that should be included, let me know. I’ll work to get it in a future edition. For contact information, see the "We’d Like Your Feedback!" section later in the preface.

Conventions in This Book

The following typographical conventions are used in this book:

Italic

Introduces new terms, URLs, commands, file extensions, filenames, directory or folder names, and UNC pathnames.

Constant width

Indicates command-line elements, computer output, and code examples.

Constant width italic

Indicates placeholders (for which you substitute an actual name) in examples and in registry keys.

Constant width bold

Indicates user input.

Tip

Indicates a tip, suggestion, or general note. For example, we’ll tell you when you need to use a particular version or whether an operation requires certain privileges.

Warning

Indicates a warning or caution. For example, we’ll tell you when Active Directory does not behave as you’d expect or whether a particular operation has a negative impact on performance.

Method, Property, Field Name Qualification

When introduced for the first time, the methods are qualified with their class names; for example, when you see the FindAddress method from the FindServiceSoap, you see it as the FindServiceSoap.FindAddress method, while in subsequent sections you see it as only FindAddress.

Code Samples

All code samples are presented in C#. Many code samples and snippets are not wrapped in try/catch blocks for the sake of simplicity; however, it is good practice to wrap the application logic in try/catch blocks to avoid unexpected errors.

Companion Material

This book comes with companion material that includes sample code for:

MapPoint 2004

All code samples have references to MapPoint 2004; however, since future releases will be backward-compatible with MapPoint 2004, you should not have issues when running samples on future versions of MapPoint.

MapPoint Web Service

Samples require credentials. The companion material contains shared credentials for the MapPoint Web Service staging environment. Please note that these credentials are only included for the sake of convenience, and it is recommended to request your own credentials when you start developing with MapPoint Web Service. Abuse of these credentials may result in denied access to the Web Service, causing inconvenience to your fellow readers of this book.

MSN Virtual Earth

Sample code uses the undocumented Virtual Earth APIs.

Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact O’Reilly for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: "Programming MapPoint in .NET by Chandu Thota. Copyright © 2006 O’Reilly Media, Inc., 0-596-00906-2.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact the publisher at [e-mail].

Other Resources

Writing a technical book is never complete, especially when four different products and technologies are covered in one book. For more information, you can always go to the MSDN online developer center for all your documentation needs. You can read about all of the MapPoint products at http://www.msdn.com/mappoint.

You can also check my MSDN weblog at http://blogs.msdn.com/cthota.

Safari® Enabled

When you see a Safari® Enabled icon on the cover of your favorite technology book, it means the book is available online through the O’Reilly Network Safari Bookshelf.

Safari offers a solution that’s better than e-books. It’s a virtual library that lets you easily search thousands of top technology books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current information. Try it for free at http://safari.oreilly.com.

We’d Like Your Feedback!

The information in this book has been tested and verified to the best of our ability, but mistakes and oversights do occur. Please let us know about errors you may find, as well as your suggestions for future editions, by writing to:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax)

You also can send us messages using email. To be put on our mailing list or to request a catalog, send email to:

[e-mail]

To ask technical questions or comment on the book, send email to:

[e-mail]

For corrections and amplifications to this book, check out O’Reilly Media’s online catalog at:

http://www.oreilly.com/catalog/mappoint/

Acknowledgments

Thanks to O’Reilly for signing this book. I’d also like to thank my editor, Simon St.Laurent, for being patient with me and providing words of encouragement throughout the process.

Thanks to the MapPoint team for creating a fantastic set of products to write about!

Thanks to Wayne S. Freeze, Michael Schmalz, and Dylan Vance for serving as the technical reviewers for this book. All of them caught numerous oversights and mistakes and made the book much better as a result. I’d like especially to thank Dylan’s thoughtful and thorough feedback.

I would like to thank Stephen Lawler for writing the foreword and laying out the vision for the future of MapPoint Development Platform for this book. I also would like to extend my special thanks to Anurag Sharma and Jay Nanduri for their encouragement and cooperation throughout this effort.

Writing a book is a collective effort and it was simply not possible to finish this project without help from the following people: Amit Dekate, Andrew Hwangbo, Brian Jepson, Caleb Thompson, Chris Pendleton, David Buerer, Eric Frost, Norm Bryar, Rachel Falzone, Richard Waymire, Stuart Macrae, and Steve Lombardi.

Finally, I would like to thank to my wife, Taarinya, for putting up with me when I essentially ignored the world writing this book through many weeks, long weekends, and late nights.