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

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

olpcMAP.net/json?page=2

Etc...

Load points in custom-sized chunks

olpcMAP.net/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.

olpcMAP.net/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:

olpcMAP.net/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:

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

Using a map marker as the central point:

olpcMAP.net/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):

olpcMAP.net/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:

olpcMAP.net/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):

• http://olpcMAP.net/json?country=Nepal
• http://olpcMAP.net/json?country=Australia
• http://olpcMAP.net/json?country=Canada
• http://olpcMAP.net/json?state=SouthCarolina

We are currently working with OLPC Mongolia to cluster their region

Request Formats

Data is in JSON by default.

Get JavaScript which you can add via <script src="SCRIPT"></script> by adding &format=js

olpcMAP.net/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
  • GET http://olpcmap.net/contact?id=359001 for a contact form for this point
  • POST http://olpcmap.net/contacter?id=359001 with variables
    • login = an e-mail address
    • message = the message
  • Edit an existing marker by ID
    • GET http://olpcmap.net/makePoint?id=ID&name=NAME&pt=LAT,LNG&icon=ICON_URL&details=DETAILS&photo=URL&album=URL&group=NAME
  • Create a new marker by not sending an ID variable
    • GET http://olpcmap.net/makePoint?name=NAME&pt=LAT,LNG&icon=ICON_URL&details=DETAILS&photo=URL&album=URL&group=NAME
    • this returns a JavaScript function call with the ID of the marker just created:
    • identifyNewMarker("ID_VALUE");

• 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.

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.