OlpcMAP/data-api
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.appspot.com/olpcMAP/json?page=1 -- these points have the most recent updates
mapmeld.appspot.com/olpcMAP/json?page=2
Etc...
Load points in custom-sized chunks
mapmeld.appspot.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.appspot.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.appspot.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.appspot.com/olpcMAP/json?center=Boston,MA&km-distance=30
Using a map marker as the central point:
mapmeld.appspot.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):
mapmeld.appspot.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.appspot.com/olpcMAP/json?region=Mongolia
Request Countries or States
Areas with large numbers of markers ( > 25 ) should be clustered to avoid problems with the server, and user experience. These are currently represented by a red T on the map (this should change ASAP!)
The clusters can be set up by admins by setting a country or state attribute (these are the only ones enabled):
- mapmeld.appspot.com/olpcMAP/json?country=Nepal
- mapmeld.appspot.com/olpcMAP/json?country=Australia
- mapmeld.appspot.com/olpcMAP/json?country=Canada
- mapmeld.appspot.com/olpcMAP/json?state=SouthCarolina
We are currently working with OLPC Mongolia to cluster their region
Request Individual Points
Request a single point using the variable byid
mapmeld.appspot.com/olpcMAP/json?byid=359001
Request Formats
Data is in JSON by default.
Get JavaScript which you can add via <script src="SCRIPT"></script> by adding &format=js
mapmeld.appspot.com/olpcMAP/json?region=Mongolia&format=js
Data Model
The JSON object has an array of points called pts
Each point has these attributes:
- name - a string with title, person's name, or person's privacy-enhanced name (for example, Adam Holt may be in the database, but output will be privacy-enhanced to Adam H). A good example of privacy-enhanced names is at http://olpcmap.net/json?center=SanJose,CA&km-distance=20
- 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.appspot.com/olpcMAP/contact?id=359001 for a contact form for this point
- POST mapmeld.appspot.com/olpcMAP/contacter?id=359001 with variables
- login = an e-mail address
- message = the message
- Edit an existing marker by ID
- GET mapmeld.appspot.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.appspot.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.