Package: highcharts-maps
High-end data and map visualizations for the Python ecosystemHighcharts Maps for Pythonis an extension to theHighcharts Core for Pythonlibrary, providing
a Python wrapper for theHighcharts MapsJavaScript data visualization library.Highcharts Maps for Pythonalso supportsHighcharts Core (JS)- the core Highcharts data visualization libraryTheHighcharts Export Server- enabling the programmatic creation of static
(downloadable) data visualizationsThe library supports Highcharts (JS) v.10.2 and higher, including Highcharts (JS) v.11.2.0.Highcharts Maps for Pythonis 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 dataframesPySpark. 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.COMPLETE DOCUMENTATION:https://maps-docs.highchartspython.com/en/latest/index.htmlThe Highcharts for Python ToolkitTheHighcharts Maps for Pythonlibrary is part of the broaderHighcharts for Python Toolkit,
which together provides comprehensive support across the entireHighchartssuite of data visualization libraries:Python LibraryJavaScript LibraryDescriptionHighcharts Core for PythonHighcharts Core (JS)(this library) the core Highcharts data visualization libraryHighcharts Stock for PythonHighcharts Stock (JS)the time series visualization extension to Highcharts CoreHighcharts Maps for PythonHighcharts Maps (JS)the map visualization extension to Highcharts CoreHighcharts Gantt for PythonHighcharts Gantt (JS)the Gantt charting extension to Highcharts Core(all libraries in the Python toolkit)TheHighcharts Export Serverenabling the programmatic creation of static (downloadable) data visualizationsInstallationTo installHighcharts Maps for Python, just execute:$pipinstallhighcharts-mapsBefore you install, please be aware of the following “hard” dependencies:Python 3.10 or higherHighcharts Maps (JS) v.10.2 or higher (not technically a Python dependency, but
it won’t work with earlier versions of Highcharts)Highcharts Core for Pythonv.1.3 or higheresprima-pythonv.4.0 or higherrequestsv.2.31 or highervalidator-collectionv.1.5 or highertopojsonv.1.5 or highergeojsonv.3.0 or higherYou can find more information about soft and development dependencies in thecomplete documentation.Why Highcharts for Python?Highchartsis 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
fantasticdemo visualizations.As a suite of JavaScript libraries,Highchartsis
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 theHighcharts for Python Toolkitto bridge that gap.Highcharts for Pythonprovides Python object representation forallof the
JavaScript objects defined in theHighcharts (JavaScript) API. It provides automatic
data validation, and exposes simple and standardized methods for serializing those Python
objects back-and-forth to JavaScript object literal notation.Highcharts Maps for Pythonin particular provides support for
theHighcharts Mapsextension, which is
designed to provide extensive map and data visualization capabilities optimized for
GIS (Geographic Information System) data visualization, with
robust interactivity. For ease of use, it also includes the full functionality ofHighcharts Core for Pythonas well.Key Highcharts Maps for Python FeaturesClean 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 inHighcharts Maps for Python. This
includes the over 70 data visualization types supported byHighcharts Coreand the four
core map visualizations available inHighcharts 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.NoteSee also:Supported VisualizationsSimple 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-providedHighcharts 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 Pythonhas 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 Pythonautomatically 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
the Highcharts for Python toolkit applies Pythonic syntax with automatic conversion between
Pythonicsnake_casenotation and JavaScriptcamelCasestyles.Highcharts Maps for Pythonvs AlternativesFor a discussion ofHighcharts Maps for Pythonin comparison to alternatives, please see
theCOMPLETE DOCUMENTATION:https://maps-docs.highchartspython.com/en/latest/index.htmlHello World, and Basic Usage1. Import Highcharts Maps for Python# PRECISE IMPORT PATTERN# 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:fromhighcharts_maps.chartimportChartfromhighcharts_maps.global_options.shared_optionsimportSharedMapsOptionsfromhighcharts_maps.optionsimportHighchartsMapsOptionsfromhighcharts_maps.options.plot_options.mapimportMapOptionsfromhighcharts_maps.options.series.mapimportMapSeries# CATCH-ALL IMPORT PATTERN# 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 is also a known anti-pattern, as it obscures the namespace within the# library. Both may be acceptable to you in your use-case, but do use at your own risk.# Import objects from the catch-all ".highcharts" module.fromhighcharts_mapsimporthighcharts# You can now access specific classes without individual import statements.highcharts.Charthighcharts.SharedMapsOptionshighcharts.HighchartsMapsOptionshighcharts.MapOptionshighcharts.MapSeries2. Create Your Chart# from a primitive array, using keyword argumentsmy_chart=Chart(data=[[1,23],[2,34],[3,45]],series_type='line')# from a primitive array, using the .from_array() methodmy_chart=Chart.from_array([[1,23],[2,34],[3,45]],series_type='line')# from a Numpy ndarray, using keyword argumentsmy_chart=Chart(data=numpy_array,series_type='line')# from a Numpy ndarray, using the .from_array() methodmy_chart=Chart.from_array(data=numpy_array,series_type='line')# from a JavaScript filemy_chart=Chart.from_js_literal('my_js_literal.js')# from a JSON filemy_chart=Chart.from_json('my_json.json')# from a Python dictmy_chart=Chart.from_dict(my_dict_obj)# from a Pandas dataframemy_chart=Chart.from_pandas(df)# from a PySpark dataframemy_chart=Chart.from_pyspark(df,property_map={'x':'transactionDate','y':'invoiceAmt','id':'id'},series_type='line')# from a CSVmy_chart=Chart.from_csv('/some_file_location/filename.csv')# from a HighchartsOptions configuration objectmy_chart=Chart.from_options(my_options)# from a Series configuration, using keyword argumentsmy_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 SharedMapsOptionsfromhighcharts_maps.global_options.shared_optionsimportSharedMapsOptions# from a JavaScript filemy_global_settings=SharedMapsOptions.from_js_literal('my_js_literal.js')# from a JSON filemy_global_settings=SharedMapsOptions.from_json('my_json.json')# from a Python dictmy_global_settings=SharedMapsOptions.from_dict(my_dict_obj)# from a HighchartsOptions configuration objectmy_global_settings=SharedMapsOptions.from_options(my_options)4. Configure Your Chart / Global Settingsfromhighcharts_core.options.titleimportTitlefromhighcharts_core.options.creditsimportCredits# EXAMPLE 1.# Using dictsmy_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 objectsfromhighcharts_core.options.titleimportTitlefromhighcharts_core.options.creditsimportCreditsmy_title=Title(text='The Title for My Chart',floating=True,align='center')my_chart.options.title=my_titlemy_credits=Credits(text='Chris Modzelewski',enabled=True,href='https://www.highchartspython.com')my_chart.options.credits=my_credits5. Generate the JavaScript Code for Your ChartNow 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 stringjs_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 stringglobal_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 bytesmy_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 Notebookmy_chart.display()Getting Help/SupportTheHighcharts for Python Toolkitcomes 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 theHighcharts ForumsUseStack Overflowwith thehighcharts-for-pythontagReport bugs or request featuresin the library’s Github repositoryFile a support ticketwith usSchedule a live chat or video callwith usFOR MORE INFORMATION:https://www.highchartspython.com/get-helpContributingWe welcome contributions and pull requests! For more information, please see theContributor Guide.
And thanks to all those who’ve already contributed!TestingWe useTravisCIfor our build automation andReadTheDocsfor our documentation.Detailed information about our test suite and how to run tests locally can be
found in our Testing Reference.