OlpcMAP/data-api

From OLPC
< OlpcMAP
Revision as of 11:25, 15 February 2011 by Ndoiron (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Request URLs

Request Global Points

There are several methods to load global points. The first page (page=0) is different from the subsequent pages. Read carefully.

Load 50 points at a time

mapmeld.com/olpcMAP/json?page=1 -- these points have the most recent updates

mapmeld.com/olpcMAP/json?page=2

Etc...

Load points in custom-sized chunks

mapmeld.com/olpcMAP/json?page=1&per_page=40

At this time, you can request up to 50 items per page.

Load static points and clusters of points

The points on page=0 are apart from the database. They are not expected to change as frequently as other points. Points can come and go from this list, so don't make a static copy of it. See ajaxpts in the Additional Properties section of this page for information on handling clusters.

mapmeld.com/olpcMAP/json?page=0

  • You cannot request per_page on page=0. There are 60 static points and 4 clusters as of this writing
  • Regular markers on page=0 may be missing attributes such as .photo, .icon, and .details
  • Do not expect order of attributes on page=0 markers to be consistent - they were added manually
  • AJAX clusters on page=0 may be missing attributes such as .icon

Request by Distance from Point

Load points a given distance from a latitude,longitude center with the llcenter variable:

mapmeld.com/olpcMAP/json?llcenter=42.356261,-71.05957&km-distance=30

Using Yahoo Maps + Where On Earth ID, you can set the center to be almost any placename:

mapmeld.com/olpcMAP/json?center=Boston,MA&km-distance=30

Using a map marker as the central point:

mapmeld.com/olpcMAP/json?id=336003&km-distance=600

The URL above loads points within 600 kilometres of the map marker at http://olpcMAP.net?id=336003

Request by Area

Load points within a box (use format north,east,south,west) -- use Multiple Areas when crossing International Date Line:

mapmeld.com/olpcMAP/json?llregion=20.38154,-69.579162,17.555734,-74.98993

Using Yahoo Maps + Where On Earth ID, you can set the region to almost any placename:

mapmeld.com/olpcMAP/json?region=Mongolia

Request Multiple Areas

Load points within two or more boxes (format north,east,south,west|n2,e2,s2,w2)

mapmeld.com/olpcMAP/json?llregions=20,-126,-53.8,-180|20,180,-53.8,113


Request Countries or States

Areas with large numbers of markers ( > 25 ) may be clustered to avoid problems with user experience. These are currently represented by a blue square

The clusters can be set up by admins by setting a country or state attribute (these are the only ones enabled):

  • mapmeld.com/olpcMAP/json?country=Nepal
  • mapmeld.com/olpcMAP/json?country=Australia
  • mapmeld.com/olpcMAP/json?country=Canada
  • mapmeld.com/olpcMAP/json?state=SouthCarolina

We are working with OLPC Mongolia to cluster their region

Request Individual Points

Request a single point using the variable byid

mapmeld.com/olpcMAP/json?byid=359001

Exclude Individual Points

KML only Exclude points using the variable nid. This is useful if you're loading nearby points via KML and handle the user's main point separately.

mapmeld.com/olpcMAP/kml?region=Pennsylvania&nid=359001

Request Formats

Maps

If there is no data format requested, you recieve a region-specific olpcMAP.net map. For example, http://olpcMAP.net?region=Mongolia will focus on Mongolia, and http://olpcMAP.net/json?region=Mongolia will show data

Embeddable Images

Add &map=image to request an image. Special properties to customize the image:

  • w width
  • h height
  • z zoom

For example, http://olpcMAP.net?map=image&id=437001&km-distance=40&w=650&h=100&z=10

Embeddable or Low-Bandwidth Maps

Add &map=quick to request these fully-functioning HTML maps

http://olpcMAP.net?map=quick&region=Kenya

Data

JSON

Data is in JSON by default.

JavaScript

Get JavaScript by adding &format=js -- you can use this to kick-start your map via <script src="SCRIPT"></script>

mapmeld.com/olpcMAP/json?region=Mongolia&format=js

KML

KML works in nearly any web map (Google, ArcGIS, Bing, OpenLayers, CloudMade) with only a few lines of code. We can use this to kick-start local mapping communities and bring in developers who are less familiar with Google Maps.

Request a KML map by changing /json to /kml on any request.

mapmeld.com/olpcMAP/kml?region=Caribbean

Download KML for Google Earth and keep it updated by adding &nl=true

mapmeld.com/olpcMAP/kml?region=Mongolia&nl=true

RSS/GeoRSS

Get an RSS feed of recent edits to the map

mapmeld.com/olpcMAPolpc/feed

Data Model

The JSON object has an array of points called pts

Each point has these attributes:

  • id - a string which can be used to edit markers or access contact information (see next section)
  • pt - a array of two decimal numbers with format [ LATITUDE , LONGITUDE ]
  • icon - string URL to the marker's preferred icon. Values such as an empty string or "DEFAULT" can be any icon
  • details - string - text description of this point; may include HTML links, ordered lists, and unordered lists
  • photo - string URL to a photo connected to this marker; empty string means that none is known
  • album - string URL to a photo album connected to this marker; empty string means that none is known
  • group - string with a group name, URL to the group's website, or an empty string if no group was given

Additional Properties

Depending on your query, the top-level JSON response object can have other properties, documented here:

  • page - returned in page= queries - a page number
  • ajaxpts - returned in page=0 queries - an array of point cluster objects with the following properties:
    • name - a name for this cluster of points
    • query - the JSON API URL to request the points
    • pt - the central point of the query, represented by an array with format [ LATITUDE, LONGITUDE ]
    • icon - a suggested icon for this cluster or to the markers produced from it
  • center - returned in llcenter= and center= queries - an array of two numbers with format [ LATITUDE , LONGITUDE ]
  • kmdistance - returned in llcenter and center= queries - a number representing the search radius
  • country - returned in country= queries
  • state - returned in state= queries
  • region - returned in llregion= and region= queries - an object with number properties region.north, region.south, region.east, and region.west.


Marker Interactions

  • GET mapmeld.com/olpcMAP/contact?id=359001 for a contact form for this point
  • POST mapmeld.com/olpcMAP/contacter?id=359001 with variables
    • login = an e-mail address
    • message = the message
  • Edit an existing marker by ID
    • GET mapmeld.com/olpcMAP/makePoint?id=ID&name=NAME&pt=LAT,LNG&icon=ICON_URL&details=DETAILS&photo=URL&album=URL&group=NAME
  • Create a new marker by sending an e-mail instead of an ID variable
    • GET mapmeld.com/olpcMAP/makePoint?name=NAME&pt=LAT,LNG&icon=ICON_URL&details=DETAILS&photo=URL&album=URL&group=NAME&mail=sample@example.com
    • this returns a JavaScript function call with the ID of the marker just created:
    • identifyNewMarker("ID_VALUE");

Setting up your Info Window

olpcMAP.net uses JavaScript functions setupContent(markerIndex) and infoSlice(tabCode,markerIndex) to format all map point info windows, tabs, and content.

If your code focuses on the base map and clustering, you hope to extend this info window code, or you want a starting point for your own marker renderer, try using this function.


Feature / Search Requests

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=OlpcMAP/data-api&oldid=252969"