TagMaps Web Services: Roll Your Own API
Want to throw text or tags from your own data onto a map? TagMaps was designed to make it dead-easy for you to overlay your geographically-located text/tag data onto a map. Simply follow these three steps:
- Generate a web service that returns GeoRSS XML, based on your data, in response to bounding-box-and-zoom-level REST queries.
- Use the embed form to generate the embed code for the TagMaps SWF module. Make sure you specify your own data source from step 1.
- Put the HTML embed code from step 2 into your web page.
- That's it! No step 4. But keep reading if you want more details.
Your Web Service
Your data source web service should accept REST-style queries specifying a bounding box, and return GeoRSS objects in the format specified below.
For example, say your web service is located at http://mytagmaps.com/data.php. Your service should be able to reply with GeoRSS to a query such as: http://mytagmaps.com/data.php?minlat=37.4&minlon=-122&maxlat=37.6&maxlon=-121.8
Where the parameters are (testing):
| Parameter | Value | Description |
|---|---|---|
| minlat | float | the latitude of bottom-left corner of the requested bounding box |
| minlon | float | the longitude of bottom-left corner of the requested bounding box |
| maxlat | float | the latitude of top-right corner of the requested bounding box |
| maxlon | float | the longitude of top-right corner of the requested bounding box |
| zoom | integer | Zoom level of the map (using Yahoo! Maps zoom convention: "16" = world, "5" roughly corresponds to a country, "10" is city, and "1" is the lowest street level.) |
Try your service with these parameters before you embed it into TagMaps!
The TagMaps application will call your data web service on every map-based action such as pan, zoom in and out, or navigate. In the case that your data service return results that exceed the viewable map area specified by the bounding box, Tag Maps would simply not render those results. However, it could be useful to specify points that are slightly outside the bounding box, as Tag Maps will be able to cache those results, and render them immdiately if the user pans the map.
Cross domain file
In order for a SWF file to read data in another sandbox, it must be granted explicit permission by stakeholders of that other sandbox. (More details on the Flash Player security model) So in order for your embedded TagMaps swf file to access your custom data source, you will need to add a file called "crossdomain.xml" to the document root of your webserver. The file should contain the following:
GeoRSS Data Source Format
TagMaps uses a simplified version of the GeoRSS XML format. The following table shows the GeoRSS fields that TagMaps uses, and a sample GeoRSS file that TagMaps can read.
Channel Sub-Elements
| Parameter | Value | Description |
|---|---|---|
| link | string (required) | A URL to be used to link the user back to the referring page. Presently not displayed |
| title | string (required) | The anchor text for the URL specified by the link. |
| item | enclosing tag | Describes an individual item to be placed on the map. Full specification for the item element is in the table below. |
Item Sub-Elements
| Parameter | Value | Description |
|---|---|---|
| title | string (required) | Text to be displayed on the map |
| category | integer (0-100) | The size of the text to be displayed. The value scales the text between the minimum (0) and maximum (100) font sizes. |
| guid | string | a id that can be used to uniquely identify the given item. |
| geo:lat | floating-point number (required) | The latitude of the location. |
| geo:long | floating-point number (required) | The longitude of the location. |
Sample GeoRSS Response
Developer Support & Community
If you're building something cool with the TagMaps web services, please let us know or just swing on by the mailing list and shoot the wind with other TagMaps developers/users. Do it all in the tagmaps discussion group.