= Mapuntu =

== Project ==
Mapuntu is the project for maps.ubuntu.com. Currenly it let us map the location of ubuntu servers, but in further versions al types of location based items should be visible on the map.

Mapuntu should provide an API to add,remove and update markers on the map, show additional information on the markers when clicked upon.

The different markers should be structurable, searchable for Ubuntu users.

== API ==
=== GeoIP ===
http://maps.ubuntu.com/API/geoip/

POST params optional:
 * ip<string> Ip adress (if not specified, the ip of the request itself is used)

HttpResponse (JSON):
 * area_code<int>
 * city<string>
 * country_code<string-2>
 * country_code3<string-3>
 * country_name<string>
 * dma_code<int>
 * latitude<float>
 * longitude<float>
 * metro_code<int>
 * postal_code<string>
 * region<string>
 * region_name<string>
 * time_zone<string>

=== Register an item ===
http://maps.ubuntu.com/API/register/

POST params required:
 * title<string> The title of the marker
 * marker_type<int> see [[#List of active marker Types]]
 * lng<float> longitude
 * lat<float> latitide

POST params optional:
 * tags<commaseparated-string>
 * lifetime<string> (default variable by marker_type) The amount of time the marker should be visible (1y = 1 year, 2w = 2 weeks, 4d = 4 days)
 * [marker_type specific params]

HttpResponse (JSON):
 * id<integer> the id of the marker
 * secret<hash> a secret code for validation (not everyone can delete the items, only the one who created the items)

(--[[https://launchpad.net/~csenger|csenger]] There seems to be no way to call unregister/update if the returned secret got lost. I'd not expect users to keep track of hashes. It should accept a (hashed) secret and an email address to retrieve a lost secret as optional parameters.)

=== Unregister an item ===
http://maps.ubuntu.com/API/unregister/<secret>/

HttpResponse (JSON):
 * success<true/false>
 * [errors<dict>] example: {"parameter1": "Error message"[, "parameter2": "Error message"]}

=== Update an item ===
http://maps.ubuntu.com/API/update/<secret>/

POST params:
 * title<string>
 * type<string>
 * lng<float>
 * lat<float>
 * tags<commaseparated-string>
 * lifetime<string>
 * [marker_type specific params]

HttpResponse (JSON):
 * success<true/false>
 * [errors<dict>] example: {"parameter1": "Error message"[, "parameter2": "Error message"]}}}

=== List of active marker Types ===
http://maps.ubuntu.com/API/types/

HttpResponse (JSON):
List of
 * name<string> the name of the type
 * icon_url<string> the url of the type's icon
 * description<string> the discription
 * additional_parameters<list[string]>


== Django Implementation ==
{{{
class Tag(models.Model):
    tag = models.CharField(max_length=25)

class TypeAttribute(models.Model):
    attribute = models.CharField(max_length=50)    

class Type(models.Model):
    name = models.CharField(max_length=25)
    description = models.TextField()
    active = models.BooleanField(default=True)
    marker_icon = models.ImageField(upload_to='markers')
    template = models.FileField(upload_to='templates')
    allowed_attibutes = models.ManyToManyField(TypeAttribute)
    default_lifetime = models.DateField(default=datetime.timedelta(weeks=52))
    max_lifetime = models.DateField(default=datetime.timedelta(weeks=3*52))

class Marker(models.Model):
    lat = models.FloatField()
    lng = models.FloatField()
    marker_type = models.ForeignKey(Type)
    tags = models.ManyToManyField(Tag)
    title = models.CharField(max_length=50)
    content = models.TextField(verbose_name=_('Content')) # Pickled dictionary
    more_info_url = models.URLField(null=True, blank=True)
    secret = models.CharField(max_length=16)
    creation_date = models.DateField(auto_now_add=True)
    update_date = models.DateField(auto_now=True)
    expiration_date = models.DateField(blank=False)
}}}

== Marker Types ==

=== Ubuntu Server ===
 * Ubuntu version
 * Server Type ('Webserver, Fileserver, Proxyserver, Mailserver')
 * Comments

=== Ubuntu User ===
 * Name
 * IRC Name
 * Launchpadname
 * Comments


== Design Questions ==

=== The map could become overloaded with 'deprecated' markers, how to prevent this ===
I was thinking about adding a enddate/lifetime the the request. If the lifetime is past, the marker will be hidden on the map. Should there be a maximum lifetime? -- [[https://launchpad.net/~ronnie.vd.c|ronnie.vd.c]]
(-- [[https://launchpad.net/~kim0|kim0]] +1 on lifetime)
(--[[https://launchpad.net/~csenger|csenger]] Wouldn't it be good to have different defaults for lifetime? I'd not expect that my Ubuntu User marker will expire (by default))

=== Markers can contain additional information when clicked upon, should we add restrictions ===
There are several methods to include information to the marker (link->iframe to external site, HTML, HTML-template+json-data, plain text). Should we add restrictions to this? -- [[https://launchpad.net/~ronnie.vd.c|ronnie.vd.c]]
(-- [[https://launchpad.net/~kim0|kim0]] AFAICT data should be minimal, I'd go for simply HTML)

=== In what extend should we allow customization of the markers ===
Should we allow different icons, should we standarize the information content for different types of markers (Persons, Events, etc)? This involves from our side to have a lot of types available, but have much consistency.
If users can infuence the content information, its possible to create items for items even we cant think of (both in the good and bad way). -- [[https://launchpad.net/~ronnie.vd.c|ronnie.vd.c]]
(-- [[https://launchpad.net/~kim0|kim0]] Let's keep us in control of the types, anyone having a valid new type can file a bug to add it (like Global Jam marker or so)