An introduction to arcpy.mapping for ArcGIS Server developers

Python is very popular among ArcGIS Desktop developers because it helps automate workflows for map production, management of documents, GIS analysis, and so on. ArcGIS Server developers generally use Python to create geoprocessing services. In this post we will introduce a new Python module arcpy.mapping that is included in ArcGIS 10.

The purpose of arcpy.mapping is to aid with the manipulation of map documents (.mxd) and layer files (.lyr) . For ArcGIS Server, the most obvious use of arcpy.mapping is to support high quality print functionality through a web service. For example, you can use arcpy.mapping to programmatically open a map document, zoom to an area of interest, set the map scale, change the title of the page layout, and create a PDF document that people can download through a browser and then send to the printer.

While you could do all of this with ArcObjects within a server object extension, you may want to consider scripting with Python because the code is comparatively simple. Also, with Python scripting you can take advantage of all the goodies of the geoprocessing service framework, including a REST endpoint that works with all the ArcGIS Web APIs, asynchronous execution, error reporting, and so forth.

If you are not familiar with geoprocessing services, have a look at this overview of geoprocessing with ArcGIS Server. Once you understand how geoprocessing services work, the Python code is the easy part. In this five minute video we go over the examples and patterns for using arcpy.mapping with ArcGIS Server.

Some arcpy.mapping examples

We’ve put together three arcpy.mapping examples to get you started:

  • Simple Map Export–This is a very simple app, probably the best to warm-up. It shows you the basics of using the ExportToPDF operation. Try it with your own data, and look at the source code of both the web app and Python script to get started. The source code is available here.
  • Map Export Plus–This takes the previous example further: it shows you how to manipulate the visibility of layers within a map document, plus introduces a creative way to handle graphics. The source code is also included as part of the item.
  • Strip Map–In this example, arcpy.mapping is used in combination with Data Driven Pages to create multiple maps along a user-defined polyline. This is also known as a strip map, which is useful to map linear infrastructures like a pipeline. The maps are added to a multi-page PDF map document. In each page we include an overview of the area, a detailed map of a portion of your line, and a terrain profile. The source code is available here.

In all examples above, the arcpy.mapping code follows a simple pattern: Your web mapping application displays data from web services. Some of these are dynamic, others are cached… Your Python script is set so it has access to map documents .(mxd files) on your server. These map documents point to the same data that your web mapping app is using. When the geoprocessing service is invoked, the Python script loads the map document, changes some of its properties such as the extent of the map, text elements in the layout or even the visibility of layers, and then calls ExportToPDF to generate a pdf file that can be downloaded by the client.

Tips for arcpy.mapping

Here are a few things we’ve learned in our work with arcpy.mapping.

  • Map automation, not quick print–arcpy.mapping is really about map automation. It is great if you need to generate high quality maps; that is, maps that print at the specific scale you want, with the look and feel that you can give your maps in ArcGIS Desktop, including all the goodies of ArcMap layouts like dynamic text elements, fancy legends, scale elements, index grids, and so forth. If you are really looking for a quick and dirty print tool, client-side printing might be a simpler option. Here are some quick print samples for Flex and Silverlight.
  • Caution with large maps–With arcpy.mapping, you can generate very large maps: 33 by 44 inch maps for example. But you need to keep in mind that the bigger the map, the more CPU-intensive the operation will be on your server. If you use imagery, it’s going to eat up a lot of memory too. It’s generally good to keep a low ratio of geoprocessing service instances to your available cores to avoid overutilization in concurrency scenarios. For example, do not start more than two instances of your geoprocessing service per available core. That way, concurrent requests will be queued and will not exhaust available resources on your server.
  • Use local data for large format maps–Large format maps only work really well when you are using data that is local to your Python script. So let’s say that you include data from ArcGIS Online base maps in your map. Well, these map tiles were cooked with 96 DPI, which is not going to look well on paper unless you print on a 11×17 inch piece of paper or smaller. If it happens that you want to use your own cached maps in your web apps, we recommend that you go ahead and point your web app to the cached service, but point your Python script to the original data sources that were used to generate that map cache. That way you get the speed of the web, and the best high quality for your PDF. In other words, your web app looks at map tiles, but your python script goes straight to the live data and generates the PDF out of that.
  • Managing graphics and visibility of layers–The biggest challenge with arcpy.mapping is to sync up the contents of your web mapping application with the map documents your Python script uses. It’s easy to sync up things like the extent of the map, its scale, and its layout text, but what about selected features, filters, graphics, and visibility of layers? In the examples above, we provided source code to you that shows how to do all of this. You will notice that handling graphics and visibility of layers requires quite a bit of logic in both your web application and Python script. We wanted to show a couple of creative ways to do this today, but you should be aware that we are working to beef up arcpy.mapping in our next version of ArcGIS to simplify some of these challenging aspects.

Contributed by Ismael Chivite, Mark Smith, and David Spriggs of Esri

This entry was posted in Services and tagged , , . Bookmark the permalink.

Leave a Reply


  1. mingkof says:

    How to set the size of the PDF?

  2. shekhawatravi says:

    My requirement is such: My paper size of pdf would varies based on the number of features user has selected on the map, and then calculating GeomeryBag of those features. e.g. A0 to A4 size.
    So my concern is, Can I set These sizes dynamically in arcpy.mapping?

  3. shekhawatravi says:

    My requirement is such: My paper size of pdf would varies based on the number of features user has selected on the map, and then calculating GeomeryBag of those features. e.g. A0 to A4 size.
    So my concern is, Can I set These sizes dynamically in arcpy.mapping?

  4. gamreddy says:

    Can I use blank templates (no data) and add data dynamically? In that way I don’t have to worry about syncing wma and templates.

  5. jeffmoulds says:

    At version 10.1, we added the ConvertWebMapToMapDocument function to arcpy.mapping to support high quality web map printing and exporting in web applications. To get you started using the new function, we published two tutorials that demonstrate workflows such as outputing printer-friendly PDF documents containing high-quality vector output for service layers: