Please note: This is a preliminary release of linking functionality with À-la-carte. The parameters given here may change, in which case we will be sure to update this document and make an announcement on the main page. If you want to see any additional functionality or have questions, feel free to leave a comment.
Linking Basics
There are four main ways to link to an À-la-carte map from an external website:
- Through the Map URL option in the File menu
- Through a feature name
- Through a Pleiades id
- Through a json string (with optional zoom and center parameters)
Linking through the Map URL option, feature name or Pleiades ID is the most straightforward process; however creating a json string is relatively easy and gives you many more options, including displaying multiple names or Pleiades IDs at once. All of these different procedures are explained bellow.
Linking Through Map URL
Under the File menu in the map panel you will find a new option: Map URL.
Clicking on this option will spawn a popup which has a clickable link to the current map state:
In this case the url is:
If you click on this link, a new window will appear zoomed and centered to your current map view. You can simply cut and paste this URL into your own site, which will allow visitors to interact with any map that you create.
At the moment this only supports features that are in the Pleiades data set, so any customization will be lost (this is due to the fact that the URL generated will certainly become too large if we allow for customization of that kind). We are working on an alternative method for linking to maps using POST parameters, but for now this is an easy and quick way to generate customized map views for external websites.
Linking Through a Feature Name
Simply append the following to the url:
?name=somename
So, to link to a map with Athens already placed on it, your url would look like the following:
http://awmc.unc.edu/awmc/applications/alacarte/?name=athens
This parameter behaves exactly like the search function in the main application, so placing a partial name (i.e. pergam for Pergamum: http://awmc.unc.edu/awmc/applications/alacarte/?name=pergam) will return all places that have pergam in their name. Similarly, setting the parameter to Alexandria (http://awmc.unc.edu/awmc/applications/alacarte/?name=alexandria) will place all locations named Alexandria on the map.
Linking Through a Pleiades ID
Just like the name parameter, linking via a Pleiades ID is a simple matter. Just place the Pleiades ID after the ?pid= parameter (you can obtain a Pleiades ID for a feature from À-la-carte, Pelagios, or directly from Pleiades). For example, the Pleiades ID for Athens is: 579885. The URL to link to an À-la-carte map of this id is:
http://awmc.unc.edu/awmc/applications/alacarte/?pid=579885
Note that, unlike the names parameter, the pid parameter will only return one feature. This is very useful if you only want to display a specific feature on the map.
Linking Through json
This option gives you the most control and flexibility when linking to À-la-carte, and is extremely useful for mapping existing projects. Do not be intimidated by the format, as .json is designed to be human readable and is easily modified. It is simply a formated list and is trivial to make from any source of names or Pleiades IDs.
You three main choices when sending json to À-la-carte:
- A list of names
- A list of Pleiades IDs
- “Raw” json directly from Pleiades
All of these options share the same parameter: jsonGet
Linking Through json: Names
For this, the json should look like the following:
{“names”:[{"name":somename], {“name”:”some other name”}]}
So, for a list of Alexandria, Athens, Rome, and Sparta the json is:
{“names”: [{"name": "Alexandria"}, {"name": "Athens"}, {"name": "Rome"}, {"name": "Sparta"}]}
Simply add
?jsonGet=
to the front of your json string and append this to the url, as in the following example:
You will now see all of the places populated on the map. Once again, this behaves exactly like the search function on the map, so you may get multiple results for a single place name.
Linking Through json: Pleiades IDs
This functionality is nearly identical to the names discussed above, although it uses different keys in the json string.
The json should follow this format:
{“pids”: [{"pid": "somepid"}, {"pid": "some other pid"}]}
A potential pid list should look like the following:
{“pids”: [{"pid": "30205"}, {"pid": "876562"}, {"pid": "422995"}, {"pid": "550812"}]}
Simply add
?jsonGet=
to the front of your .son string and append this to the url, as in the following example:
You will now see all of the places populated on the map.
Optional Parameters
You can also add the following optional parameters to the json string (as shown in the map URL example): zoom and center. The “zoom” parameter corresponds to an openlayers zoom level, formatted as follows: “zoom”:”some zoom number” while the center is the longitude and latitude of where you want the center of a map to be, formatted as “center”:”lon=some longitude,lat=some latitude” . For instance, in the map url example this looks like the following:
You can use these parameters to link to a precise location and zoom level of your choosing.
Linking Through json: Raw Pleiades .json
If you have “raw” json data from Pleiades, you can add this after the ?jsonGet= parameter as well. For instance, the Pleiades json for Athens (http://pleiades.stoa.org/places/579885/json) is the following:
{"connectsWith": ["579888", "580123"], "recent_changes": [{"modified": "2012-10-23T19:39:21Z", "principal": "sgillies"}, {"modified": "2012-02-15T06:40:36Z", "principal": "admin"}], "description": "A major Greek city-state", "title": "Athenae", "reprPoint": [23.719536999999999, 37.970793], "features": [{"geometry": {"type": "Point", "bbox": [23.726464, 37.971687000000003, 23.726464, 37.971687000000003], "coordinates": [23.726464, 37.971687000000003]}, "type": "Feature", "properties": {"snippet": "Settlement; 750 BC - AD 640", "link": "http://pleiades.stoa.org/places/579885/dare-location", "description": "Representative point location, site precision", "title": "DARE Location"}, "id": "dare-location"}, {"geometry": {"type": "Point", "bbox": [23.719536999999999, 37.970793, 23.719536999999999, 37.970793], "coordinates": [23.719536999999999, 37.970793]}, "type": "Feature", "properties": {"snippet": "Unknown; 750 BC - AD 640", "link": "http://pleiades.stoa.org/places/579885/darmc-location-21246", "description": "Point location", "title": "DARMC location 21246"}, "id": "darmc-location-21246"}], "names": ["Athenae", "Athens"], "type": "FeatureCollection", "id": "579885", "bbox": [23.719536999999999, 37.970793, 23.726464, 37.971687000000003]}
Simply append this to the map url as follows:
You will then see Athens placed on the map.
Follow Us!