OlpcMAP/data-api: Difference between revisions
mNo edit summary |
No edit summary |
||
(3 intermediate revisions by the same user not shown) | |||
Line 87: | Line 87: | ||
=Request Formats= |
=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®ion=Kenya |
|||
===Data=== |
|||
====JSON==== |
====JSON==== |
||
Line 104: | Line 122: | ||
Request a KML map by changing /json to /kml on any request. |
Request a KML map by changing /json to /kml on any request. |
||
<tt> |
<tt>mapmeld.com/olpcMAP'''/kml'''?region=Caribbean</tt> |
||
Download KML for Google Earth and keep it updated by adding &nl=true |
Download KML for Google Earth and keep it updated by adding &nl=true |
||
<tt> |
<tt>mapmeld.com/olpcMAP'''/kml'''?region=Mongolia'''&nl=true'''</tt> |
||
====RSS/GeoRSS==== |
====RSS/GeoRSS==== |
||
Line 114: | Line 132: | ||
Get an RSS feed of recent edits to the map |
Get an RSS feed of recent edits to the map |
||
<tt> |
<tt>mapmeld.com/olpcMAPolpc'''/feed'''</tt> |
||
=Data Model= |
=Data Model= |
Latest revision as of 15:25, 15 February 2011
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®ion=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:
- 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.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.