Honeycomb DocsURL Parameters
URL Parameters is a feature that lets you dynamically change a Honeycomb map at load time. For example, you may want to add a certain data source, or analyze a specific place in response to user input. To use URL Parameters to configure Honeycomb, you simply append them to the end of the Honeycomb base URL.
How to use URL parameters
URL parameters are additional strings which are added to the end of the base Honeycomb URL. The diagram below shows the base Honeycomb URL (https://app.honeycomb.place) with two added parameters: configFile and fullscreen:
Available URL Parameters
configFile
configFile=
The configFile URL parameter takes the URL string of a remote config file in JSON format, and causes Honeycomb to immediately apply the configuration specified in this file to the map. If other URL Parameters are present, they will take precedence over the configuration specified in the file. For more information, see Config Files.
TIP
You must encode your config file URL as a URI component before using it as a URL parameter. This is necessary to replace reserved characters like : with escape sequences like %3A. There are functions in JavaScript, Python and many other languages which can do this.
ANOTHER TIP
For this parameter to work properly, the config file must be accessible for Honeycomb. If you are hosting the file yourself, you may need to modify the access-control-allow-origin CORS header to allow app.honeycomb.place.
Example
https://app.honeycomb.place/?configFile=https%3A%2F%2Fraw.githubusercontent.com%2Fcarstonhernke%2Fdemo-h3-data%2Fmain%2Fconfig_files%2Fbasic_config.jsonhttps://app.honeycomb.place/?configFile=https%3A%2F%2Fraw.githubusercontent.com%2Fcarstonhernke%2Fdemo-h3-data%2Fmain%2Fconfig_files%2Fbasic_config.jsonfullscreen
fullscreen
The fullscreen URL parameter causes Honeycomb to start with both the left and right sidebars minimized. It does not require a value to function, only that the parameter name is present.
The fullscreen parameter is useful if you have already created a finished analysis you want to share, or if you want to embed Honeycomb in an iframe (see Using URL parameters with iframes).
https://app.honeycomb.place/?fullscreenhttps://app.honeycomb.place/?fullscreeninitialData
initialData= The initialData URL parameter lets you load a remote data file at the same time Honeycomb loads. This is useful if you need to change the data file you load based on user input. An example use case would be loading a CSV file of data for the specific country the user is interested in.
The initialData parameter can be used with any of the data formats which Honeycomb supports. See Data Formats for details. You must make sure that your data file is accessible to Honeycomb. If you are hosting the file yourself, you may need to modify the access-control-allow-origin CORS header to allow app.honeycomb.place.
TIP
You must encode your initial data URL as a URI component before using it as a URL parameter. This is necessary to replace reserved characters like : with escape sequences like %3A. There are functions in JavaScript, Python and many other languages which can do this.
https://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880_zstd.parquethttps://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880_zstd.parquetaggregationType
aggregationType=SUM
The aggregationType URL parameter MUST be used in conjunction with the initialData parameter. It is used to specify how the imported columns in the dataset will be aggregated. The aggregation type will apply to all columns. If you need more fine-grained control over aggregation type per column, consider using a Config File instead.
Allowed Values
SUM, AVG, MIN, MAX
Example
https://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880_zstd.parquet&aggregationType=SUMhttps://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880_zstd.parquet&aggregationType=SUMinitialPlace
initialPlace
The initialPlace URL parameter is used to add a single place to the map as it loads. It MUST be used in conjunction with the initialData parameter. The place must be a Point, Line, or Polygon specified in Well-Known Text (WKT) format.
https://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880_zstd.parquet&aggregationType=SUM&initialPlace=POLYGON%20((-122.450352%2037.805444%2C%20-122.427006%2037.807614%2C%20-122.424946%2037.792897%2C%20-122.449579%2037.791337%2C%20-122.450352%2037.805444))https://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880_zstd.parquet&aggregationType=SUM&initialPlace=POLYGON%20((-122.450352%2037.805444%2C%20-122.427006%2037.807614%2C%20-122.424946%2037.792897%2C%20-122.449579%2037.791337%2C%20-122.450352%2037.805444))mapId
mapId
The mapId URL parameter is used to reference a unique analysis when sharing or embedding URLs from the Honeycomb Web App.
Using URL parameters with iframes
URL parameters work great with iframes, letting you customize Honeycomb maps on your site on-the-fly without the effort of installing additional JavaScript libraries.
Here is an iframe which utilizes the initialData, aggregationType, initialPlace, and fullscreen URL parameters to pre-load an analysis of population in the Marina District of San Francisco.
Here is the actual code which is used to embed the iframe above:
<iframe src='https://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880.parquet&aggregationType=SUM&initialPlace=POLYGON%20((-122.450352%2037.805444%2C%20-122.427006%2037.807614%2C%20-122.424946%2037.792897%2C%20-122.449579%2037.791337%2C%20-122.450352%2037.805444))&fullscreen' style='height: 400px; width: 100%;'></iframe><iframe src='https://app.honeycomb.place/?initialData=https%3A%2F%2Fapp.honeycomb.place%2Fdata%2Fworld_population_sorted_rg_122880.parquet&aggregationType=SUM&initialPlace=POLYGON%20((-122.450352%2037.805444%2C%20-122.427006%2037.807614%2C%20-122.424946%2037.792897%2C%20-122.449579%2037.791337%2C%20-122.450352%2037.805444))&fullscreen' style='height: 400px; width: 100%;'></iframe>