Highcharts Maps for Python
High-end data and map visualization for the Python ecosystem
Highcharts Maps for Python is an extension to the Highcharts Core for Python library, providing a Python wrapper for the Highcharts Maps JavaScript data visualization library.
Highcharts Maps for Python also supports
Highcharts Core (JS) - the core Highcharts data visualization library
The Highcharts Export Server - enabling the programmatic creation of static (downloadable) data visualizations
Highcharts Maps for Python is fully integrated with the broader Python ecosystem, offerin gnative integrations with:
Jupyter Labs/Notebook. You can now produce high-end and interactive plots and renders using the full suite of Highcharts visualization capabilities.
Pandas. Automatically produce data visualizations from your Pandas dataframes
PySpark. Automatically produce data visualizations from data in a PySpark dataframe.
GeoPandas. Automatically incorporate GIS / map visualizations with data from your GeoPandas GeoDataFrames.
Topojson. Automatically visualizes TopoJSON map geometries.
Geojson. Automatically visualizes GeoJSON map geometries.
The Highcharts for Python Toolkit
The Highcharts Maps for Python library is part of the broader Highcharts for Python Toolkit, which together provides comprehensive support across the entire Highcharts suite of data visualization libraries:
Python Library |
JavaScript Library |
Description |
|---|---|---|
(this library) the core Highcharts data visualization library |
||
the time series visualization extension to Highcharts Core |
||
Highcharts Maps for Python |
the map visualization extension to Highcharts Core |
|
the Gantt charting extension to Highcharts Core |
||
(all libraries in the Python toolkit) |
The Highcharts Export Server |
enabling the programmatic creation of static (downloadable) data visualizations |
Installation
To install Highcharts Maps for Python, just execute:
$ pip install highcharts-maps
Dependencies
Note
Highcharts Maps for Python has several types of dependencies:
hard dependencies, without which you will not be able to use the library at all,
soft dependencies, which will not produce errors but which may limit the value you get from the library,
developer dependencies that contributors will need in their local environment, and
documentation dependencies that are necessary if you wish to generate (this) documentation
Warning
If these hard dependencies are not available in the environment where Highcharts Maps for Python is running, then the library will simply not work. Besides Highcharts Maps itself, all of the other hard dependencies are automatically installed when installing Highcharts Stock for Python using:
$ pip install highcharts-maps
Highcharts Maps v.10.2 or higher
Note
Not technically a Python dependency, but obviously Highcharts Maps for Python will not work properly if your rendering layer does not leverage Highcharts Maps.
highcharts-core v.1.7.0 or higher
esprima-python v.4.0 or higher
requests v.2.31 or higher
validator-collection v.1.5 or higher
topojson v.1.5 or higher
geojson v.3.0 or higher
Warning
If these soft dependencies are not available in the environment where
Highcharts Maps for Python is running, then the library will throw a
HighchartsDependencyError exception when
you try to use functionality that relies on them.
No error will be thrown until you try to use dependent functionality. So for
example, if you call a from_pandas() method but
pandas is not installed, you will get an error.
You can install all soft dependencies by executing:
$ pip install highcharts-maps[soft]
Warning
You will not be able to run unit tests without the Pytest test framework and a number of necessary extensions. To install the developer (and soft, and documentation) dependencies, execute:
$ pip install highcharts-maps[dev]
pytest v.7.1 or higher
pytest-cov v.3.0 or higher
pytest-xdist v.2.5 or higher
python-dotenv v. 0.21 or higher
Note
python-dotenv will fail silently if not available, as it will only leverage natural environment variables rather than a
.envfile in the runtime environment.pytz v.2022.1 or higher
tox v.4.0.0 or higher
Warning
You will not be able to generate documentation without Sphinx and a number of necessary extensions. To install the documentation dependencies, execute:
$ pip install highcharts-maps[docs]
Sphinx v.6.1.3 or higher
Sphinx RTD Theme v.1.2 or higher
sphinx-tabs v.3.4.1 or higher
Sphinx Toolbox v.3.4 or higher
Why Highcharts for Python?
Highcharts is the world’s most popular, most powerful, category-defining JavaScript data visualization library. If you are building a web or mobile app/dashboard that will be visualizing data in some fashion, you should absolutely take a look at the Highcharts suite of solutions. Take a peak at some fantastic demo visualizations.
As a suite of JavaScript libraries, Highcharts is written in JavaScript, and is used to configure and render data visualizations in a web browser (or other JavaScript-executing) environment. As a set of JavaScript libraries, its audience is JavaScript developers. But what about the broader ecosystem of Python developers and data scientists?
Given Python’s increasing adoption as the technology of choice for data science and for the backends of leading enterprise-grade applications, Python is often the backend that delivers data and content to the front-end…which then renders it using JavaScript and HTML.
There are numerous Python frameworks (Django, Flask, Tornado, etc.) with specific capabilities to simplify integration with Javascript frontend frameworks (React, Angular, VueJS, etc.). But facilitating that with Highcharts has historically been very difficult. Part of this difficulty is because the Highcharts JavaScript suite - while supporting JSON as a serialization/deserialization format - leverages JavaScript object literals to expose the full power and interactivity of its data visualizations. And while it’s easy to serialize JSON from Python, serializing and deserializing to/from JavaScript object literal notation is much more complicated.
This means that Python developers looking to integrate with Highcharts typically had to either invest a lot of effort, or were only able to leverage a small portion of Highcharts’ rich functionality.
So we wrote the Highcharts for Python Toolkit to bridge that gap.
Highcharts Maps for Python provides support for the Highcharts Maps extension, which is designed to provide extensive map and data visualization capabilities optimized for GIS data visualization, with robust interactivity. For ease of use, it also includes the full functionality of Highcharts for Python as well.
Key Highcharts Maps for Python Features
Clean and consistent API. No reliance on “hacky” code,
dictand JSON serialization, or impossible to maintain / copy-pasted “spaghetti code”.Comprehensive Highcharts support. Every single Highcharts chart type and every single configuration option is supported in Highcharts Maps for Python. This includes the over 70 data visualization types supported by Highcharts Core and the four core map visualizations available in Highcharts Maps.
Every Highcharts for Python library provides full support for the rich JavaScript formatter (JS callback functions) capabilities that are often needed to get the most out of Highcharts’ visualization and interaction capabilities.
See also
Simple JavaScript Code Generation. With one method call, produce production-ready JavaScript code to render your interactive visualizations using Highcharts’ rich capabilities.
Easy Chart Download. With one method call, produce high-end static visualizations that can be downloaded or shared as files with your audience. Produce static charts using the Highsoft-provided Highcharts Export Server, or using your own private export server as needed.
Asynchronous Map Data Retrieval. To minimize the amount of data transferred over the wire, Highcharts Maps for Python has built-in support for the configuration of asynchronous client-side retrieval of your map data.
Automatic TopoJSON Optimization. To minimize the amount of data transferred over the wire, Highcharts Maps for Python automatically converts your map geometries to highly-efficient TopoJSON topologies while still allowing you to work with GeoJSON data if you choose to.
Integration with GeoPandas, Pandas, and PySpark. With two lines of code, produce a high-end interactive visualization of your GeoPandas, Pandas, or PySpark dataframes.
Consistent Code Style. For Python developers, switching between Pythonic code conventions and JavaScript code conventions can be…annoying. So Highcharts for Python applies Pythonic syntax with automatic conversion between Pythonic
snake_casenotation and JavaScriptcamelCasestyles.
Highcharts Maps for Python vs Alternatives
Since Highcharts Maps is such a popular high-end GIS data visualization library for JavaScript, there are a variety of alternative ways of working with it in Python. We have an obvious bias towards Highcharts Maps for Python, but it may be useful to compare it against some commonly-used alternatives:
By far, this is the most common approach to integrating Highcharts into your Python code. As a developer, you know that your JavaScript front-end will be using Highcharts (JS). So you work in your Python backend to deliver the data to your front-end that your front-end will need.
There are many patterns for rolling your own Highcharts + Python implementation, but the patterns we have seen most often include:
Your Python code is “hands off” - it does not touch any data visualization configuration or manipulation. All of that gets handled in your JavaScript front-end code.
This approach is very “clean” from a code architecture standpoint. However, in practice it often problematic because it delegates data manipulation and (potentially) business logic handling to your front-end code. Depending on the overall design of your software, it can make your code harder to maintain. Furthermore, depending on your team composition, it may simply be impractical for your team.
Your Python code constructs a JSON object (typically by serializing a Python
dict to JSON) which gets delivered to your JavaScript front-end,
which then hands the JSON code off to Highcharts to visualize.
This approach is also fairly clean. JSON, after all, is easy in both Python and JavaScript. But JSON is a suboptimal transport mechanism for some of Highcharts’ most powerful features: callback functions. As this is native JavaScript code, they cannot really be serialized securely to JSON and then executed directly by the Highcharts library. So while simple use cases can be handled through JSON serialization, many more robust or sophisticated uses of Highcharts (which would rely on formatters, event handling, etc.) will simply not work.
The most sophisticated implementations we have seen actually replicate much of the functionality of the Highcharts for Python Toolkit, where they construct JavaScript object literal notation serialization and de-serialization for their robust use cases.
This approach is the most robust of all custom implementations, for obvious reasons. However, as with any full-fledged custom implementation your mileage may vary. For the most sophisticated Highcharts + Python applications that we have seen, this has been the approach of choice because it eliminates all of the limitations of the other approaches mentioned.
But, to create custom serialization on a one-off/custom basis can take a large amount of effort. Constructing a comprehensive solution like the Highcharts for Python Toolkit is deeply non-trivial, and so we think it’s wiser to use a toolkit where:
the implementation/heavy lifting has been done for you
you are guaranteed ongoing maintenance
you are guaranteed available support
In many cases, particularly when working with data science teams who are data scientists first and software developers by necessity, the team traditionally turns to weaker data visualization packages simply because those packages are available in Python.
This option has historically - sadly - been fairly common, and is one of the primary reasons for our development of the Highcharts for Python Toolkit. Even though plenty of developers coming to Python from the JavaScript ecosystem ask “Why can’t we just use Highcharts?”, many in the Python ecosystem will answer “because it’s a pain to do”. So they turn to Highcharts alternatives that are are more limited but more Python-friendly.
Tip
When to use it?
In practice, we find that rolling our own solution is great when doing a limited number of simple and static (non-interactive) visualizations. Then you can just quickly use some simple JSON serialization, and rapidly get a high-quality chart visualized cleanly using Highcharts. But anything more robust than that is going to prove “hacky” and incredibly difficult to maintain.
Which is why we created the Highcharts for Python Toolkit in the first place, so that:
you gain the ability to use as much or as little of Highcharts rich functionality as you need
you get native integration with key Python ecosystem members “out of the box”
you don’t have to worry about maintaining the “glue” code connecting your Python implementation with Highcharts (JS)
you have support available when you need it
The panel-highcharts library is - honestly - fantastic. It is a excellent wrapper for the Highcharts (JS) suite to enable exploratory data analysis (EDA) in Jupyter Notebooks or in Holoviz web applications.
There are really two limitations to be aware of:
It relies on the Jupyter Labs/Notebook or Holoviz context, which means that it would be hard to utilize unless you happen to be working in Jupyter or Holoviz.
It relies on configuration via
dictobjects that map 1:1 to the Highcharts API. In practice, this forces the developer to switch between Pythonicsnake_caseconvention and JavaScriptcamelCaseconventions within the same code. Not a big problem, but annoying.To really benefit from its capabilities, it requires a fair bit of Holoviz boilerplate and widget configuration, which can be complicated, verbose, and “fiddly”.
Tip
When to use it?
If your use case is limited to highly-interactive exploratory data analysis in a Jupyter Labs/Notebook environment and you are willing to construct some complicated Holoviz widget configuration code, it may be worth considering this library.
However, those are some pretty specific gating conditions. For integration with a non-Jupyter application? That’s not what the Highcharts for Python Toolkit was designed for.
The python-highcharts library is a great start to working with Highcharts in the Python ecosystem. However, given that its last release was in December 2018, it can best be considered “stale” and “impractical”.
While the design of this library is an excellent start, and in some ways served as an inspiration for the Highcharts for Python Toolkit, it is not a practical solution for several key reasons:
“Stale” / Unmaintained? The last commit to the library was in 2018, almost four years ago (as of the time of writing).
Not comprehensive. The library is not comprehensive relative to the Highcharts API, and does not support many of the features and chart types introduced over the last several years. Not all Highcharts chart types and classes are supported, and not all Highcharts functionality is available.
JavaScript-forward style. The library relies heavily on Python
dictobjects but relying on the JavaScript style for naming conventions. This is not that big of a deal, but when building complex applications in Python it can be annoying to constantly context-switch from Pythonsnake_casestandards to JavaScriptcamelCasestyle.
Tip
When to use it?
We wouldn’t rely heavily on it, as it no longer seems to be maintained, has fallen out of alignment with more recent releases of the Highcharts suite and its functionality is (by design) not comprehensive.
The PyHighcharts library is closest in philosophy to the Highcharts for Python Toolkit, but it is also much more limited than any of the other alternatives discussed:
Dead library. This library hasn’t seen any new releases since 2015. There’s an open question whether it will even import / work in modern versions of Python (we haven’t tested it meaningfully in the last couple of years).
Extremely limited support. By design, this library only supports a handful of the visualizations offered by Highcharts (JS). Furthermore, even for those visualization types, only a limited number of configuration options are available. And because the library has not been updated in about seven years, there’s an open question whether it will even work to produce relevant visualizations.
Tip
When to use it?
We wouldn’t. While you might still be able to use the other alternatives listed, this is one that we would not recommend be touched under any circumstances.
Hello World, and Basic Usage
1. Import Highcharts Maps for Python
Tip
Best Practice!
This method of importing Highcharts Maps for Python objects yields the fastest
performance for the import statement. However, it is more verbose and requires
you to navigate the extensive Highcharts Maps for Python API.
# Import classes using precise module indications. For example:
from highcharts_maps.chart import Chart
from highcharts_maps.global_options.shared_options import SharedMapsOptions
from highcharts_maps.options import HighchartsMapsOptions
from highcharts_maps.options.plot_options.map import MapOptions
from highcharts_maps.options.series.map import MapSeries
Caution
This method of importing Highcharts Maps for Python classes has relatively slow performance because it imports hundreds of different classes from across the entire library. This performance impact may be acceptable to you in your use-case, but do use at your own risk.
# Import objects from the catch-all ".highcharts" module.
from highcharts_maps import highcharts
# You can now access specific classes without individual import statements.
highcharts.Chart
highcharts.SharedMapsOptions
highcharts.HighchartsMapsOptions
highcharts.MapOptions
highcharts.MapSeries
2. Create Your Chart
# from a primitive array, using keyword arguments my_chart = Chart(data = [[1, 23], [2, 34], [3, 45]], series_type = 'line') # from a primitive array, using the .from_array() method my_chart = Chart.from_array([[1, 23], [2, 34], [3, 45]], series_type = 'line') # from a Numpy ndarray, using keyword arguments my_chart = Chart(data = numpy_array, series_type = 'line') # from a Numpy ndarray, using the .from_array() method my_chart = Chart.from_array(data = numpy_array, series_type = 'line') # from a JavaScript file my_chart = Chart.from_js_literal('my_js_literal.js') # from a JSON file my_chart = Chart.from_json('my_json.json') # from a Python dict my_chart = Chart.from_dict(my_dict_obj) # from a Pandas dataframe my_chart = Chart.from_pandas(df) # from a PySpark dataframe my_chart = Chart.from_pyspark(df, property_map = { 'x': 'transactionDate', 'y': 'invoiceAmt', 'id': 'id' }, series_type = 'line') # from a CSV my_chart = Chart.from_csv('/some_file_location/filename.csv') # from a HighchartsOptions configuration object my_chart = Chart.from_options(my_options) # from a Series configuration, using keyword arguments my_chart = Chart(series = my_series) # from a Series configuration, using .from_series() my_chart = Chart.from_series(my_series)
3. Configure Global Settings (optional)
# Import SharedMapsOptions from highcharts_maps.global_options.shared_options import SharedMapsOptions # from a JavaScript file my_global_settings = SharedMapsOptions.from_js_literal('my_js_literal.js') # from a JSON file my_global_settings = SharedMapsOptions.from_json('my_json.json') # from a Python dict my_global_settings = SharedMapsOptions.from_dict(my_dict_obj) # from a HighchartsOptions configuration object my_global_settings = SharedMapsOptions.from_options(my_options)
4. Configure Your Chart / Global Settings
from highcharts_maps.options.title import Title from highcharts_maps.options.credits import Credits # EXAMPLE 1. # Using dicts my_chart.title = { 'align': 'center', 'floating': True, 'text': 'The Title for My Chart', 'use_html': False, } my_chart.credits = { 'enabled': True, 'href': 'https://www.highchartspython.com/', 'position': { 'align': 'center', 'vertical_align': 'bottom', 'x': 123, 'y': 456 }, 'style': { 'color': '#cccccc', 'cursor': 'pointer', 'font_size': '9px' }, 'text': 'Chris Modzelewski' } # EXAMPLE 2. # Using direct objects from highcharts_maps.options.title import Title from highcharts_maps.options.credits import Credits my_title = Title(text = 'The Title for My Chart', floating = True, align = 'center') my_chart.options.title = my_title my_credits = Credits(text = 'Chris Modzelewski', enabled = True, href = 'https://www.highchartspython.com') my_chart.options.credits = my_credits
5. Generate the JavaScript Code for Your Chart
Now having configured your chart in full, you can easily generate the JavaScript code that will render the chart wherever it is you want it to go:
# as a string js_as_str = my_chart.to_js_literal() # to a file (and as a string) js_as_str = my_chart.to_js_literal(filename = 'my_target_file.js')
6. Generate the JavaScript Code for Your Global Settings (optional)
# as a string global_settings_js = my_global_settings.to_js_literal() # to a file (and as a string) global_settings_js = my_global_settings.to_js_literal('my_target_file.js')
7. Generate a Static Version of Your Chart
# as in-memory bytes my_image_bytes = my_chart.download_chart(format = 'png') # to an image file (and as in-memory bytes) my_image_bytes = my_chart.download_chart(filename = 'my_target_file.png', format = 'png')
8. Render Your Chart in a Jupyter Notebook
my_chart.display()
Getting Help/Support
The Highcharts for Python Toolkit comes with all of the great support that you are used to from working with the Highcharts JavaScript libraries. When you license the toolkit, you are welcome to use any of the following channels to get help using the toolkit:
Use the Highcharts Forums
Use Stack Overflow with the
highcharts-for-pythontagReport bugs or request features in the library’s Github repository
File a support ticket with us
FOR MORE INFORMATION: https://www.highchartspython.com/get-help
Contributing
We welcome contributions and pull requests! For more information, please see the Contributor Guide. And thanks to all those who’ve already contributed:
Chris Modzelewski (@hcpchris / @insightindustry)
Testing
We use TravisCI for our build automation and ReadTheDocs for our documentation.
Detailed information about our test suite and how to run tests locally can be found in our Testing Reference.