{"id":23464,"date":"2023-04-09T13:19:53","date_gmt":"2023-04-09T13:19:53","guid":{"rendered":"https:\/\/www.highcharts.com\/blog\/?p=23464"},"modified":"2026-01-13T11:29:53","modified_gmt":"2026-01-13T11:29:53","slug":"highcharts-maps-python-asynchronous-map-data","status":"publish","type":"post","link":"https:\/\/www.highcharts.com\/blog\/integration\/highcharts-maps-python-asynchronous-map-data\/","title":{"rendered":"Highcharts Maps for Python – Working with Asynchronous Map Data"},"content":{"rendered":"

Map visualizations are more complicated than standard charts because you\u2019re actually visualizing two distinct types of data: yes, you still have your quantitative data that you want to visualize but you also have to provide Highcharts Maps for Python<\/b> with the map data on which your quantitative data should be visualized.<\/p>\n

How you supply your map data to Highcharts Maps for Python is a very important question because it can have significant performance implications for your code. Map data can be very verbose, and as such it can take a relatively time on the wire. For this reason, Highcharts Maps for Python lets you choose where your map data actually gets loaded: in your Python code, or in the JavaScript code produced by Highcharts Maps for Python.<\/p>\n

Tip<\/b>
\nBest practice<\/b>: Because map data can be verbose and relatively large on the wire, we typically prefer to load it asynchronously in the JavaScript code produced by Highcharts Maps for Python. We\u2019ll only load it synchronously in Python if our use case really calls for it (for example, programmatic creation of charts for download).<\/i><\/p>\n

Applying Map Data<\/h2>\n

If you load your map data synchronously in your Python code, you\u2019ll configure your map data using a MapData<\/code> instance. If you load your map data asynchronously in your JavaScript code, then in Python you\u2019ll set your configuration up using an AsyncMapData<\/code> instance.<\/p>\n

In both cases, you can apply your map data to either the Chart instance as a whole using the Chart<\/code> instance\u2019s .set_map_data()<\/a><\/code> method, or to a specific series instance using that series instance\u2019s .set_map_data()<\/code> method. The syntax for this method is the same, whether you\u2019re using AsyncMapData<\/code> or MapData<\/code>. Assuming your Chart<\/code> instance is called my_chart<\/code> and your map data is in a variable called my_map_data<\/code> you just call:<\/p>\n

# Set the chart\u2019s map data, configured to load asynchronously\r\nmy_chart.set_map_data(my_map_data)<\/pre>\n
And that\u2019s it! Highcharts Maps for Python offers some convenience capabilities as well. For example, if you pass the .set_map_data()<\/code> method a URL, Highcharts Maps for Python will automatically convert that to an AsyncMapData<\/code> instance that will download your map data from that URL.<\/p>\n
Configuring Your AsyncMapData<\/h2>\n
While setting up asynchronous map data can be as simple as supplying a URL to the .set_map_data()<\/code> method, there are often situations where it can prove more complicated. For example, what if to access your map data you need to provide authentication credentials? Or what if you need to download a bunch of map data, but only use a subset of that map data in your visualization? Highcharts Maps for Python has you covered: The AsyncMapData<\/code> class offers you a wide range of configuration options.<\/p>\n
Authentication Credentials and Fetch Configuration<\/h2>\n
Highcharts Maps for Python gives you complete control over how your JavaScript code fetches your map data. When creating your AsyncMapData<\/code> instance, you can supply a fetch_config<\/code> property which configures how the JavaScript fetch()<\/code> call is executed.<\/p>\n
The fetch_config<\/code> property accepts a FetchConfiguration<\/a><\/code> instance. In a typical use case, you would use the FetchConfiguration<\/code>\u2019s credentials<\/code> and header<\/code> properties to supply authentication credentials with your request. Let\u2019s imagine you are using Bearer authentication. You would set your AsyncMapData<\/code> instance up as follows:<\/p>\n
from highcharts_maps.options.series.data.map_data\r\nimport AsyncMapData\r\nfrom highcharts_maps.utility_classes.fetch_configuration\r\nimport FetchConfiguration\r\n# Set the chart\u2019 s map data, configured to load asynchronously\r\nmy_fetch_config = FetchConfiguration(headers = {\r\n  'Authorization\u2019: '\r\n  Bearer '\r\n})\r\nmy_map_data = AsyncMapData(url = 'https:\/\/www.my-map-data-url.dev\/map-data.topo.json',\r\n  fetch_config = my_fetch_config)<\/pre>\n
And that\u2019s it! By default, the AsyncMapData<\/code> uses the HTTP GET method to download your map data, but if you need to use a different HTTP method (like POST or something similar) you can easily override the default using the fetch_config<\/code> properties.<\/p>\n
Using Selector Functions for Subsets of Map Data<\/h2>\n
Sometimes, you want to use only a subset of your map data in your data visualization. For example, you might want to show a map inset with more granular detail, or your geometry may contain multiple areas but your user is only interested in one, or perhaps you want to optimize your client-side performance by having your user download geometries once to cache them locally, and then rapidly switch between areas that are visualized. Highcharts Maps for Python allows you to do that by defining the .selector<\/code> property on your AsyncMapData<\/code> instance.<\/p>\n
The .selector<\/code> property lets you define a JavaScript callback function which receives one argument: topology<\/code>, which retrieves the map data downloaded from your AsyncMapData<\/code> instance\u2019s .url<\/code> property. Your JavaScript function can then perform whatever manipulations it needs to on the originally-downloaded topology. This can include selecting a subset of geometries from it, or even modifying the geometries that have been received. It\u2019s entirely up to you \u2013 provided that when all of your function\u2019s work is done, it returns a single JSON (or GeoJSON, or TopoJSON) object with a new set of geometries that your chart will then visualize.<\/p>\n
But how do you define a JavaScript function in Python? Using Highcharts Maps for Python, that is pretty simple: you create a CallbackFunction<\/code> instance and supply it to the .selector<\/code> property.<\/p>\n
There are two ways to do this. The easiest way is to pass your JavaScript function as a string to the selector<\/code> keyword argument when creating your AsyncMapData<\/code> instance. Highcharts Maps for Python will automatically take that string and convert it to a CallbackFunction<\/code> instance:<\/p>\n
from highcharts_maps.options.series.data.map_data\r\nimport AsyncMapData\r\nfrom highcharts_maps.utility_classes.fetch_configuration\r\nimport FetchConfiguration\r\n# Set the chart\u2019 s map data, configured to load asynchronously\r\nmy_map_data = AsyncMapData(url = 'https:\/\/www.my-map-data-url.dev\/map-data.topo.json',\r\n  selector = \"\"\r\n  \"function (topology) { \r\n  ...\r\n  return newTopology;\r\n}\r\n\"\"\r\n\")<\/pre>\n
As you can see, in the example above we\u2019re just passing a JavaScript function as a string to the selector<\/code> argument. That function takes one argument: topology<\/code> (the name matters) and it returns one object (its name does not matter, but we called it newTopology just to differentiate).<\/p>\n
Tip<\/b>
\nBest practice<\/b>: When supplying JavaScript code as strings to Highcharts Maps for Python, we recommend that you wrap the string in three double quotes, rather than a more conventional single quote, or even the sometimes seen double-quote. This is because by wrapping your string in three double quotes you will likely be able to avoid any escape characters in your JavaScript, making it much more readable and maintainable.<\/i><\/p>\n
We find that this approach is the easiest way to do it, since Highcharts Maps for Python does the heavy lifting for you. But if you want to create a CallbackFunction instance manually, you can do so as well:<\/p>\n
from highcharts_maps.options.series.data.map_data\r\nimport AsyncMapData\r\nfrom highcharts_maps.utility_classes.javascript_functions\r\nimport CallbackFunction\r\n# Define your CallbackFunction instance\r\nmy_selector = CallbackFunction(arguments = ['topology'],\r\n    body = \"\"\r\n    \"\r\n    ...\r\n    return newTopology;\r\n    \"\"\r\n    \")\r\n    # Set the chart\u2019 s map data, configured to load asynchronously my_map_data = AsyncMapData(url = 'https:\/\/www.my-map-data-url.dev\/map-data.topo.json',\r\n      selector = my_selector)<\/pre>\n
The code above is equivalent to the first code sample provided \u2013 just in this case we are manually creating a CallbackFunction<\/code> instance.<\/p>\n
And that\u2019s it! You\u2019ve now got your map visualizations loading and managing your geographies asynchronously in your client-side environment.<\/p>\n
Visualizing Your Visualizations<\/h2>\n
Now when you call your Chart<\/code> instance\u2019s .to_js_literal()<\/code> method, Highcharts Maps for Python will generate several JavaScript statements:<\/p>\n
    \n
  1. The first will issue an asynchronous fetch()<\/code> call to download your map geometry.<\/li>\n
  2. The second will \u2013 if your AsyncMapData<\/code> instance is using a selector<\/code> function \u2013 run your selector function on the downloaded map data.<\/li>\n
  3. And the last one will actually visualize your chart, supplying the relevant map data to it as configured.<\/li>\n<\/ol>\n
    And that\u2019s it!<\/p>\n
    More Resources<\/h2>\n
    The above tutorial is just a really simple example of how you can create rich visualizations with just a handful of method calls using Highcharts for Python. But the library offers so much more! We recommend you take a look at the following additional resources which you may find useful:<\/p>\n