Maps API

Maps are layers of tiles rendered as images in a geobrowser. The HyperCities database does not contain the map tiles itself, but rather metadata about them including links to the tile services. Map metadata in HyperCities also includes a historical element; every map has a start and end date. In most maps, these are exactly the same, set to the year the map was created or the year it represents.

Maps can be searched by text search (which searches map name, description, and creator name), bounding box, time span, owner ID, and city name.

HyperCities supports three different map formats: Google Maps Tiles (which is indicated by GraphicsMagick or MapCruncher in the tileType field), ArcGIS, and WMS. For more on the Google Maps tile format, see the Google Maps documentation. ArcGIS and WMS are dynamically-generated map images; different code must be used for displaying them in most JavaScript Map APIs. These are actually rare in the HyperCities database, but can be added to Rich Objects.

JSON output of a map service

{
   "projection": "",
   "creator": "",
   "height": 0,
   "publicationDate": {
       "date": "-0001-11-30 00:00:00",
       "timezone_type": 3,
       "timezone": "America/Los_Angeles"
   },
   "tileUrl": "http://tiles.ats.ucla.edu/tiles/Rome_1979_Scagnetti/",
   "thumbnailUrl": "",
   "tileType": "GraphicsMagick",
   "id": 123,
   "city": "Rome",
   "scale": "",
   "copyright": "",
   "title": "Roma Urbs Imperatorem Aetate",
   "imageRecord": "",
   "minZoom": "12",
   "width": 0,
   "state": 0,
   "titleEn": "The City of Rome in the Age of the Empire",
   "description": "Modern map showing what Rome was like in the time of the Emperors",
   "mapping": {
       "isCollection": false,
       "georeferences": [],
       "swLat": "41.86947600",
       "dateTo": {
           "date": "1979-12-31 00:00:00",
           "timezone_type": 3,
           "timezone": "America/Los_Angeles"
       },
       "altitude": 0,
       "kml": "",
       "dateFrom": {
           "date": "1979-01-01 00:00:00",
           "timezone_type": 3,
           "timezone": "America/Los_Angeles"
       },
       "zoom": null,
       "neLon": "12.52624200",
       "markerType": null,
       "neLat": "41.91651700",
       "isNetworkLink": false,
       "swLon": "12.44897300",
       "id": null,
       "markerState": null,
       "view": null
   },
   "callNumber": "",
   "captionEn": "With the support of the Institute of Ancient Topography for the Study of the city.  Figure drawn by Francisco Scagnetti. Power and help of Joseph greatly increased (?).  ",
   "publisher": "",
   "collectionSource": "",
   "caption": "Favente Institutio Topographiae Antiquae in Studio Urbis Formam Descripsit Franciscus Scagnetti Ope Ac Auxilio Iosephi Grande Auctus",
   "maxZoom": "19"
}

Searching Maps

To search for maps, send a GET request to /maps. At least one of the following criteria must be specified.

Name	Value Type	Description
text	String (max 255 characters)	Text to search all maps for. This will search title, creator name, and content.
bbox	Comma-separated list of floating-point values (NESW)	Geographic bounding box to search within
start	Date (YYYY-MM-DD)	Date map begins to exist
end	Date (YYYY-MM-DD)	Date map ends

Searching will return one of the following responses:

HTTP Code	Data returned	Description
200	JSON of the matching objects	Success
404	ItemNotFound exception	Failure: no objects matched the specified criteria

Creating and Editing

HyperCities does not expose an API for creating and updating maps. These have always been added directly through the database via SQL.