Page MenuHomePhabricator

Create an API to get a list of mapping services and related services
Closed, ResolvedPublic

Description

To provide a map detail view ( T131907 ), we can create an API that returns a list of map sources and some other sources in JSON format.
The data to render is such as Template:GeoTemplate.

This way the UI can manipulate the data and decide how to render it.

Implemented API: /w/api.php?action=mapdata&format=json&formatversion=2&uselang=<user-language>

Note that the backend will resolve all "localized objects" into strings. This way, api can be called with &uselang=fr to the get French localization.

{
  "services": [
    {
      "name": "OpenStreetMap",  // name of the service (can be stored as localized object {"languagecode":"value", ...}, but will return string)
      "links": [
        {
          "type": "map",        // can also be: satellite, terrain, other
          "url": "http://...",  // this value may include values like {latdegdec}, {londegdec}, etc
          "label":              // optional service type string (could be stored as localized object, but returns a string)
        },
...

Original schema ideas

Simplified schema:

Service

  • name : string (wikitext ?)
  • region : string
  • links: []
    • type : string
    • link : string
    • label : string
    • indirect: boolean

Example from the template:

| '''Open<wbr>Street<wbr>Map'''<br /><span style="font-size:11px">[[CC-BY-SA]]</span>
| [//www.openstreetmap.org/?mlat={{{latdegdec}}}&mlon={{{londegdec}}}&zoom={osmzoom}&layers=M Map]

There is a category Wikipedia articles quite specific, and the per region sections can be specific too. Can we create an API like that?

The other option is to fetch/parse the template and then filter it again and render it on the client-side. It's more limiting and harder than getting the data and letting the UI decide how to render it.

Details

Related Gerrit Patches:
mediawiki/extensions/Kartographer : masterImplement ResoureLoader module to get ext map links

Event Timeline

JGirault created this task.Sep 14 2016, 6:31 PM
Restricted Application added a project: Discovery. · View Herald TranscriptSep 14 2016, 6:31 PM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Yurik triaged this task as High priority.Sep 14 2016, 9:02 PM
Yurik added a project: Maps-Sprint.
Yurik moved this task from Backlog to To-do on the Maps-Sprint board.

Change 311316 had a related patch set uploaded (by Yurik):
Implement API to get the list of external map links

https://gerrit.wikimedia.org/r/311316

Yurik updated the task description. (Show Details)Sep 18 2016, 5:04 AM

Change 311316 merged by jenkins-bot:
Implement ResoureLoader module to get ext map links

https://gerrit.wikimedia.org/r/311316

Yurik added a subscriber: Yurik.EditedSep 20 2016, 3:52 AM

comment by @JGirault in the patch.

This kind of "links" structure (as an array with different types of links) is not ideal on the client side because I have to filter it again, even if I simply want to show "Map"-type links (and there seem to be always 1 "map"-type link).
It results in nested loops just to filter all services that have a link of type map.
Instead I would rather use the "type" as a key at the same level as "name". example:

{ name: "acme-mapper",
  "map": "http://mapper.acme.com/?ll={latdegdec},{londegdec}&z={osmzoom}&t=M&marker0={latdegdec},{londegdec},{titlee}" }

or if it may contain several links (like "others"), make it (or all types) an array

@JGirault, I thought that on a wide screen, you might want to show multiple links for the same service - e.g. you would show both map and satellite links. And only if the screen is narrow / mobile, you want to show just one type of service, and have a way to switch between them? If this is not the case, how about this structure:

{
  default: "Map",
  links: {
    "Map": [
      { name: "OpenStreetMap", featured: true, url: "http://..." },
      { name: "Google", url: "http://..." },
      ...
    ],
    "Satellite": [...],
  }
}

This way client shows just the links from one subtree. The first list to show is given by the default. You can show a combobox or buttons for easy switching.
I think localization should be done on the server, as it will be pre-cached for each user, and less work will need to be done by each client. I don't think we would gain anything from converting "kartographer-linktype-map" to "Map" on the client. There is one problem - since we use types as keys, if some translator translates two or more types with the same word, we should gracefully handle that.

With regards to all the unknown template params - lets ignore them for now, and possibly even remove them from the list until we have a better understanding of how to handle them. Lets present something to the users, and get feedback, and we can expand on additional template param support later.

@JGirault, I thought that on a wide screen, you might want to show multiple links for the same service - e.g. you would show both map and satellite links. And only if the screen is narrow / mobile, you want to show just one type of service, and have a way to switch between them?

For now the sidebar has a fixed width of 320px. It makes it work well on any device. We could try to make the sidebar larger, in order to show both Map and Satellite links, when the viewport allows it (TBD)... but then the filter links dropdown needs to handle the case when two types of links are displayed.

I'd rather get some user feedback on the existing implementation, unless we decide we prefer to wait and iterate on the design.

If this is not the case, how about this structure:

{
  default: "Map",
  links: {
    "Map": [
      { name: "OpenStreetMap", featured: true, url: "http://..." },
      { name: "Google", url: "http://..." },
      ...
    ],
    "Satellite": [...],
  }
}

This way client shows just the links from one subtree. The first list to show is given by the default. You can show a combobox or buttons for easy switching.
I think localization should be done on the server, as it will be pre-cached for each user, and less work will need to be done by each client. I don't think we would gain anything from converting "kartographer-linktype-map" to "Map" on the client. There is one problem - since we use types as keys, if some translator translates two or more types with the same word, we should gracefully handle that.

I think converting a key to a label on the client is effortless. I don't see any issue with that. However, I do see the value of having the raw map key ("map") - for presentation, filtering... - rather than an unexpectable localized key (Map, Carte, Mapa, 地图...).

With regards to all the unknown template params - lets ignore them for now, and possibly even remove them from the list until we have a better understanding of how to handle them. Lets present something to the users, and get feedback, and we can expand on additional template param support later.

Sounds fine !

MaxSem moved this task from To-do to In progress on the Maps-Sprint board.Sep 22 2016, 6:22 PM
Yurik closed this task as Resolved.Sep 22 2016, 8:12 PM
Yurik claimed this task.