API

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:

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)

(--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? -- ronnie.vd.c (-- kim0 +1 on lifetime) (--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? -- ronnie.vd.c (-- 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). -- ronnie.vd.c (-- 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)

mapuntu/API (last edited 2011-04-19 21:52:11 by ronnie.vd.c)