From OpenStreetMap Wiki
Jump to: navigation, search

Moving all osmAnd user documentation to this wiki

Overview The standing user manual written by Narayan is currently posted at . The site: is going away so the osmAnd manual and its future development must be migrated elsewhere. (see Further, the use of images (screen shots, icons, .png, .jpg) at has in the past been problematic.

Permission to use the OSM wiki in this way has already been granted and even highly encouraged! (see more below). Thanks OSM Foundation!!!

The discussion here is to confirm the move, and to thoughtfully plan out in advance the "data model" for the article / content structure here. Major initial issues that have been identified include:

  • Article titles - do they all begin with "omsAnd - " or something similar to clearly delineate the boundary between OSM and osmAnd?
  • Is there be a way to free text search ONLY osmAnd content?
  • Overall article structure - what goes on a separate article, and what is consolidated into a single article?
  • Individual article structure - can we develop a standard Wiki template, standard section headings, etc. for manual pages
  • Categories - what Wiki categories are to be used up-front?
  • Any other topology/ontology/hierarchy issues? (its so much easier to get this type of thing right at the outset)
  • Managing multiple versions in the marketplace (v1 and v2) simultaneously for a significant period of time. Migrating documentation to v2 over time.
  • Managing any special needs for the Apple IOS version and the generic Java/Linux versions?
  • Allowing easy feedback and discussion on UI, usability, initial bug reporting, workarounds
  • Allowing all Wiki pages to be easily reused in the osmAnd application itself, in the help subsystem
  • Organizing highly focused "use-case" article pages that are highly granular and user oriented, with links to other more voluminous / wider focused content.
  • Monitoring various diverse osmAnd communications channels (Google Forum, listserve, gitHub, sourceforge, etc.) and capture relevant documentation discussion for publication here on this wiki site. This site's "more enduring" wiki article pages and discussion/talk pages should be very helpful, especially over time. Material doesn't automatically "roll off the conveyor belt" here.
  • tightly integrating UI design with Documentation, particularly in the area of providing real life usability data and knowledge back to the UI designer/coders, along with passing along any bugs, and feature requests to those tracking systems without introducing "noise" and "dirt" upsetting the already formidable coders tasks.
  • Especially with the introduction of the Apple/IOS crowd really stepping up the graphic presentation and ease of use. Many more screen shots and illustrations for a much more discerning "design/visual" audience. Insure that documentation graphic quality rises over time to more of an Apple level (lets face it a huge portion of high end graphics people around have long preferred their Mac platforms. Time to step up the osmAnd presentation polish a healthy notch. Some of thee new Apple users may bring very high end graphics/presentation/UI knowledge...perhaps a few will actually contribute to the "heavy lifting" in osmAnd design, usability, UI and coding?
  • Collecting up all standing user documentation, moving it to this new location, deleting it from prior locations and provide links, communicating to all relevant groups, generating as much enthusiasm for "world class" documentation and ease of use going forward.
  • Being ever mindful that the audience is global and whatever language the documentation originates in must be easily communicated in all the world's major languages, and many of the others too. This wiki has excellent translation features.

More detail below.

PLEASE do not hesitate to comment here (registration on this site is very easy), or if you prefer, you can comment on the Google osmAnd Forum under the following topic, and comments made there will be eventually copied over here:

[Documentation] Moving all user documentation to OSM Wiki --Rjl (talk) 18:29, 10 April 2015 (UTC)

"Is there be a way to free text search ONLY osmAnd content?"
There could be a namespace in this wiki. The advanced search is able to search only in one namespace.--Zuse (talk) 08:30, 14 April 2015 (UTC)
Unfortunately we wouldn't create a namespace here for OsmAnd, because we're already using the namespace mechanism for Wiki Translation. Allowing search only within an osmAnd area of the wiki will be difficult, however (A) It might not matter too much. Users will probably figure out how to search with the word "OsmAnd" if they want to hit pages related to OsmAnd (B) there may be a possibility related to my mirroring suggestion below. -- Harry Wood (talk) 10:51, 14 April 2015 (UTC)
Separate namespaces sounds very cool but agree simple is better. Agree with Harry that including OsmAnd in the search expression should work. My understanding MediWiki uses the following free text syntax (see table below). Can imagine any of this would tax the OSM servers?
--Rjl (talk) 14:39, 14 April 2015 (UTC)
Syntax Meaning
term1 term2 logical AND (space becomes an automatic AND)
"term1 term2" both terms separated by a space must occur, in order.
-term logical NOT. Used for exclusion
AND logical AND. term1 AND term2 See above. Unless the search is enclosed in quotes, AND and space work the same.
OR logical OR
() parenthesis may be used to group Boolean expressions. (perform this Boolean evaluation first)
term* Wildcard, returns anything that matches the front part of the term
term~ Fuzzy search, returns a variety of variants including "sound-alikes", relaxed spellings, etc. Very good if you are unsure of spelling
~term "Wave search". Prevents jumping to a single title and always perform a full fuzzy search. Also stops automatic redirects and disambiguation pages. Easy mnemonic, the ~ looks like a wave...expect a flood of results.

For some of your requirements it seems like you'll need to be pulling content out of the wiki again in some automated way. In particular you mention "Allowing all Wiki pages to be easily reused in the osmAnd application itself, in the help subsystem". Particularly if you want the docs bundled with the app, you'll be needing to pull the content out of the wiki as part of your app build process. You also mentioned wanting to be able to search just within the OsmAnd docs, which is probably not going to be possible using the wiki search (except that users can obviously stick 'OsmAnd' as keyword)

Here's a thing you might be interested in though. I've been working on a "mirroring" approach recently which allowed me to create the 'session' pages on this conference website. Code for this is here: It's a caching proxy. This would potentially allow you to bring in wiki content onto with styling to fit

-- Harry Wood (talk) 11:04, 14 April 2015 (UTC)

Hi Harry. Thanks for the php program links. Very cool. I'm not a production coder so this may be out of my area of expertise. (My work requires VBA for Excel/M$FT Office coding, and the related XML). I was thinking of how WikiPedia has a desktop version and a mobile version and they simplify the presentation of content for the mobile phone. Was sort of thinking along those lines, only storing the manual pages locally on the phone vs. relying on a constantly available Internet connection in keeping with the off-line map content. Also noted there are some MediWiki "pages to book" tools that are pretty good. Might also use TTS to read the help articles when on longer trips. (requires really thinking non visually to be effective communications.) And/or use the same basic text as the basis of simple screen demo videos. (same screen demo but multiple languages) Basically trying to identify all the "use-cases" of the documentation content ahead of "over investing" in limited use, one shot formatting. We could probably use MediWiki categories to build indexes of man pages. Again, all ideas most welcome and thanks very much for your input.
--Rjl (talk) 14:39, 14 April 2015 (UTC)
May have a very stable solution all set to go. On the MediaWiki side use the Extension:Collection to enable a .zim compressed file export of a set of pages. Consumers then use the stable Kiwix off-line reader (Android, Linux, Windows, Mac.) Relatively small: 21mb application (+ data file), Available in 100+ languages, GPLv3, free & available from Google Play. ( osmAnd MAN pages collection .zim file would be quite small. Has very good cross page search. Stable. Being used to read an entire Wikipedia instance off-line. .zim file format might also be fun for "place" info from WikiPedia and perhaps, in the future, expanded use/integrate with expanded info for POIs? Might be worth playing with.
--Rjl (talk) 16:02, 15 April 2015 (UTC)

Prior discussion copied here

These were emails or other discussion channels copied here for the record:


I have already written a full-fledged user manual, and posted the text part of it here: But unfortunately I cannot insert annotated screenshots because of site limitation. I tried to link images from my Google drive, but that too does not work (I tried various tricks, but none of them worked).

The new website for OsmAnd is in the making for a very long time, but IINW there are no plans to host the user manual. I am now thinking of posting the entire manual at OSM website.

Ideas are welcome.

Regards, Narayan

-- Narayan Mar 2

Naravan, Tim

>I am now thinking of posting the entire manual at OSM website.

I love that idea!

Also agree we really need images - not only whole screen shots but shots of all the various icons and thorough write-ups of what they signify.

I'd like to see the documentation be "living" so many users could contribute over time (wiki pages seem to me to be the best format for that).

Would like to see the documentation be especially well integrated with the UI design concept(s). Start with a high level discussion of the "UI design philosophy" and show examples of how that's been implemented in a very high level / quick and easy overview. Documentation writers would need solid access to the program designers to "elicit" that knowledge, and put it in good form for broad distribution. This could be extremely valuable to communicate up front to a wide audience.

Suggest developing a list of use-cases (separate wiki-pages) that each describe a SINGLE, highly focused use-case. Ultimately these should be sorted by how frequently people hit them (a proxy for how many people want "more" documentation or "know how" in that specific area, or are greatly confused by the standing UI. Call it the "anti-intuitive index"

The ultimate goal is likely to be to have a UI that is so clean, so intuitive, so easy to use, so "predictable" that no separate documentation is needed. Second to that might be a help system inside the program (available off-line) that is "one-to-one" with the series of Wiki pages and with the built in help system that is updated as easily as the maps.

Ultimately the UI implementation should evolve based on massive UI experience. The entire UI design team should assume "the crowd is actually correct". Some of the evolution to that could easily be captured on the use-case documentation pages (wiki) under the talk pages. Likewise people reading group could capture comments and post them to the appropriate Wiki discussion page.

Last idea - it would be ideal to have a separate section of every use-case wiki documentation page captioned "Feature Requests, Bug Reporting & Temporary Workarounds". Then provide links (if any) to those systems. The idea here is never let the user "discover the hard way" that the challenge they are encountering is well understood, and in process in development. Everyone feels foolish if they feel like they are the last to know after much circuitous searching for help...

Great map, great program. So much potential!


-- rjlab

So is there a way to EMBED images in the text, while the manual is still at the google code website? Please let me know. Because otherwise I will have to enrol at OSM website and post the manual and images there.

The current manual also contains all use cases but not in example form.
Frankly I didn't get to that stage. But usually all my manuals contain real-life examples.

But the main problem I am facing is to figure out what has changed in the latest nightly. Can you guys help me with that? Just keep a thread filled with the latest changes. Then I promise I can keep the manual updated to the latest nightly.

I also want to try a "never-before"feature: With each page of manual, I also want to include the relevant bugs and suggested features.

Each bug and feature would have illustrations as well. Thus it would be a combination of "what it is right now" and "what it should be in future". Then we could have a periodic poll as to which feature looks most attractive.

- Narayan - Mar 13 2015

These use-case pages are really good idea!

- Josef Kufner Mar 12 2015

From: Rick
Sent: Wednesday, 8 April 2015, 18:54
Subject: allowable use of wiki.openstreetmap.?

Quick question re: allowable use of

OsmAnd is a very popular and broadly distributed open source mobile app (in Android, Linux, and the just released Apple IOS versions) that consumes and promotes the use of OSM data.

Would it be O.K. to transfer and continue to build the design and user manual for osmAnd on

osmAnd currently is migrating from Google to github as Google is shutting down its code repositories. osmAnd would greatly benefit from a standard MediaWiki site to host and evolve its documentation going forward.

The closer the integration with Wikipedia and OSM the better. A key feature of osmAnd is the ability to map WikiPedia articles with lat/long points easily on to a mobile map, so the technical relationship between Wikipedia, OSM, MediaWiki and osmAnd, is especially critical, on many levels, and likely to rapidly evolve going forward. With ever expanding use of cross-linked data the need for very clear communications becomes paramount.

Having osmAnd users arrive at the OSM site really helps drive active data end users to know more about the total nature of Some of those people can likely be converted to OSM contributors over time.

User manuals are closely interconnected with useability, and software interface design. As OSM data continuously expands in granularity and greatly enhanced accuracy, osmAnd software will need to follow that evolution step-by-step. As data becomes richer osmAnd must evolve its user interface to simplify access to ever greater volumes of map data without overwhelming the user. Likewise, osmAnd is challenged to migrate its software code base to ever enhanced, ever more economical hardware platforms. Yet with all this expansion the standing user base and new users can't be overwhelmed with discontinuous complexity. Documentation and communications functions are very important in easing the path forward.

Having access to the standard OSM MediaWiki platform for its design and user documentation would be a real plus. Any reasonable OSM policy could be followed by osmAnd (such as title each MediaWiki article page beginning with "osmAnd - ", etc.)

I can't imagine the total usage here would place any burden on the standing OSM servers. It might involve a dozen or so new wiki contributors and perhaps, over time, a few hundred article pages, some with static graphics (screen shots, icons, etc.). The frequency of SQL commits would be quite low as documentation tends to last for a long while (vs. breaking news, etc). User documentation for software also tends to be very low interest as soon as the user is through the learning curve and knows how to get what they want. osmAnd developers (particularly the UI group) would benefit greatly by easy to access statistics on what features are not "intuitive", where users are hitting snags, whats clearly not operating as expected, etc. Its a "closed loop" feedback system.

OSM data modelers, and data architects might also benefit by having analytical feedback from heavy users. This might help illuminate structural changes to the data models that would allow for much more efficient data exportation from the OSM data servers.

Bottom line, the more streamlined and useful the software, the more the underlying data actually gets used. Everyone wins.

  • Does the communications WG handle this type of inquiry? (If I'm way off, sorry about that, who should be contacted?)
  • Can osmAnd just "try it", and if everyone hates it at least get assistance in exporting those new MediaWiki pages to a new, independent server?
  • Who at OSM might be willing to provide some thoughtful input and guidance here?



-- rjlab 8 April 2015, 18:54

Hi Rick

Yes. This is absolutely fine. You really don't need to ask :-) (That would be the answer to your second question)

To answer your first question. CWG are a useful group of people to reach out to (though you don't need to ask) I'd be happy to help you with this process. I have a lot of experience with the OpenStreetMap wiki. What's more I would encourage you to make this move. As you've said, it will help make your documentation more easily editable, and I think it's a good way to feel more a part of the OpenStreetMap community too.

We have lots of small, medium and large software/tools/projects already documented on the OpenStreetMap wiki (where the OSM wiki becomes the primary documentation location)

Of course osmAnd is already on there, with lots of people building a single page of documentation (and linking off to your website for the details) So we'd have to figure out how to fit in with that, preferably trying to preserve some of the previous efforts. See the contributors to that page in the history:

But I guess we'd be looking at branching out into a handful of pages. You probably know the tool "Osmosis". See the way the wiki pages are structured for Osmosis: It's a set of 7 subpages, linked from the navigation box in the top right there.

How many subpages d'you think you will need for OsmAnd? Maybe each of the links here would become subpages on the wiki:

Anyway I suggest we have conversation with others over at: and we can start planning out those things.

-- User:Harry Wood - Apr 2015

Move off Google Groups to OSM listserves

Might be best to move totally away from Google. They are a great company but are clearly not open source, free, etc. as Open Street Map is. They have a great deal of time and shareholder money invested in mapping and must look to "monetizing" its audience to generate profit and provide shareholders with ever expanding financial returns.

Here are some examples of SOFTWARE projects that use the OSM listserve facilites:

  • GraphHopper -- GraphHopper Java routing engine
  • josm-dev -- JOSM developer mailing list
  • dev-OpenStreetMap -- developer discusssion
  • LoroDux-dev -- LoroDux developers
  • MapRoulette -- MapRoulette general discussion and development
  • osmosis-dev -- Osmosis development
  • Potlatch-dev -- Potlatch development
  • rails-dev -- Discussion of rails port (web site) development

The infrastructure for list maintenance is outstanding and extremely global at OSM. See:

Suggest osmAnd move all user discussion to OSM facility and consolidate.

--Rjl (talk) 18:27, 10 April 2015 (UTC)

It could be possible to create a new osmand-dev mailman mailing list hosted alongside the OSM mailing lists. Certainly we have some such lists for other tools as you've noticed.
I guess there's an archive of discussions on your google code set-up. I don't think it would be possible to migrate that into a mailman archive. It would just be a fresh new mailing list. Likewise I dont think you can migrate users. I think you'd have to ask people to manually sign-up for this new mailman list, and stop using the old one (or you can probably force people off the old one by blocking new posts I guess).
It's a separate discussion/decision to the wiki document move discussed above. And unlike wiki things, this is not easy to try and play around with, then reverse. It needs careful consideration, and then a request to OSM sysadmins to create the new mailing list (if you want to go ahead), and then a coordinated move.
--Harry Wood (talk) 10:45, 14 April 2015 (UTC)
Harry, totally agree moving from the Google Forum to a listserve is only something to do if everyone is totally on board. No one likes change for change sake, especially after a humble beginning and great growth after that. Pros: listserve is more global, more universal, easier to translate, easier to reach into the farthest corners of civilization, totally open source, not subject to centralization, very good in a deep crisis, less subject to a single point of failure, etc. Cons: tradition, familiarity, back file.
I have yet to hear back from OSMand project owners / current lead programmers on the Wiki move of documentation. Perhaps they are really busy with the new IOS release, V2 release, or documentation is perceived as low priority for the moment. Would like to know:
  • where is the source code going after shuts down?
  • where is the bug tracking going?
  • were is the feature request tracking / deciding going?
  • can bug tracking / feature request management / documentation & communication be better integrated?
I have experience with JIRA that's been positive, all of software support and maintence is however real work. Hoping to get coders and users working together a bit better here.
--Rjl (talk) 15:05, 14 April 2015 (UTC)

2012 discussion

Everything below here is a bit older pre 2012, although there are still unanswered questions there

New version

For those who haven't seen OsmAnd recently released version 1.0. Congrats to the developers. Recently added are fields for adding websites and phone numbers for each object. A good start, but it still needs a good way to add addresses. That would make the ap even better

Currently it is a little chunky to add the addr:housenumber or addr:street tags to an item but can be done. To add addresses, you have to scroll down to advanced mode > add tag > then type in the addr field in a window that is only a couple centimeters wide. The good thing is if you type "A" it goes right to the addresses and you can type in the value. If you remember the position, you can select it each time from memory.

I would like to see the address information on the home screen like the new web and phone number fields are. The extra fields would make it scroll, but I view it horizontally anyway to use my keyboard on Motorola Droid for typing in information.

There could be an option to expand or collapse the screen based on people's phone size or for people who don't care about address information. Or there the submit and cancel buttons could be repeated on top of the screen so people wouldn't need to scroll down.

I created a sample screen shot at!topic/osmand/RwlfOihhe1M. The developers are doing a great job and are open to new ideas. What do you think? Do you use the ap? What could be done to make it better? --nmixter 01:27, 6 December 2012 (BST)

I don't know if OSMand developers saw that. In the past they've not been paying attention here, and this would be the wrong place to reach them, however that may change soon (see doc moving discussion above) Anyway... I'm not clear if you were raising an issue which has since been resolved -- Harry Wood (talk) 10:33, 14 April 2015 (UTC)

OsmAnd vs. OsmAnd+

What exactly is the relationship between the two versions? The android market description of OsmAnd+ explains that OsmAnd+ is a donation version, but that cannot be the whole story - they have different version numbers and seem to offer different features. So is OsmAnd simply an old release of OsmAnd+? Are both versions GPL? --Tordanik 15:27, 14 October 2011 (BST)

Answer: Osmand is not being updated since 0.5.3 and as announced will not be updated. So, yes it is just an older version. The main development is now on Osmand plus which you can find in market as donation version, right now 0.6.8. The newest version can be found on the official website to download:
You can also download nightly builds for testing from the google code page:
Both versions are under GPL v.3 as stated in google code. The sourcecode can be also found there. --Seeebek 12:05, 15 October 2011 (BST)
That's not true. OsmAnd is still updated and just lacks some features compared to OsmAnd+ (unlimited free internal map downloads and Wikipedia POIs) --Scai (talk) 13:08, 1 January 2014 (UTC)

Source code for released versions

Is there a source code for released versions available? I can not find it. It might be buried somewhere in the git repo, but the changeset is not labeled, which makes it effectivelly unavailable. In order not to violate GNU GPL a link to the concrete changeset or an archive that corresponds exactly to the released version has to be provided by the OsmAnd project. Am I right?

(Contribution from 29. April 2012, 14:48, by Bekov (contributions). Just for the record ... please leave your signature in future, thanks :-) -- Schusch)
To fulfil the GPL requirements, the developers of OsmAnd need to make their source code code available on request to anyone who owns the compiled version. So they don't necessarily need to make it available to everyone - but if you buy it, ask them for the source code, and they refuse to give it to you, then it's clearly not GPL. --Tordanik 17:34, 19 August 2012 (BST)
And the source code is available on both, Github and Google Code. Together with the build scripts etc. How was this hard to find? --Sanderd17 11:47, 20 August 2012 (BST)
BTW, there already was a link to the source code in the article. Can it be more obvious?--Sanderd17 12:14, 20 August 2012 (BST)
maybe it's a user not so familiar with these things ... he also didn't know how to leave a signature ... so now with your assitance he should be able to find out more. -- Schusch 10:21, 21 August 2012 (BST)


The article mentions it can be run on linux. Does this mean some Android emulation or so?

There may be native support , see . I have never seen it mentioned or tested anywhere and have no idea how it works etc. Android emulation should be pretty easy, you will probably need to download the apk from either or osmand pages directly. RicoZ (talk) 11:43, 13 August 2015 (UTC)
See RicoZ (talk) 22:14, 11 June 2016 (UTC)

Is osmAnd still free?

The page currently says "OsmAnd is a collaborative, open source (GPL) software project." In 2014, its license was updated with an "exception of GPL" saying that you are not allowed to publish it in certain places without a written permission. as far as I understand it, this makes the program proprietary and (at least, technically) unredistributable by anyone except the copyright holders: the GPL requires that the redistributor must grant certain rights to the recipients, including the right to publish it in ways the exception forbids. Ineiev (talk) 07:54, 23 November 2015 (UTC)

IIRC, there was also a discussion about this point on the Osmand googlegroup mailinglist ... do an intensive search on!forum/osmand to find out. --Stephan75 (talk) 18:48, 23 November 2015 (UTC)
I'm really sorry, I'm not willing to run proprietary JavaScript Ineiev (talk) 09:11, 27 November 2015 (UTC)
lol. Bit extreme? The discussion is here if that helps. Maybe you can view that without running proprietary Javascript :-)
But anyway there doesn't appear to be any response from the "makers" of OSMAnd (or people setting the license) Just lots of users whining about the license.
Harry van der Wolf offered one explanation though: "I assume because there are a number of "pirating" applications on the play store which are 100% OsmAnd copies and are commercial as well"
Been remedied since anyway I see.
-- Harry Wood (talk) 14:45, 7 December 2015 (UTC)
The text says "should" which I read as a strong suggestion which should be respected and I certainly have full understanding for this wish. The software is still free even if this exception would be interpreted as "must" but in that case it won't be GPL anymore. However, the "must" part can be possibly enforced by the means of the artwork which is not GPL licensed. That would be very similar to the situation with Firefox and its artwork and branding. RicoZ (talk) 11:52, 24 November 2015 (UTC)
It says "GPLv3 with a restriction". the GPLv3 says that you either give the recipient full rights, without further restrictions, or mustn't redistribute at all (of course, this doesn't apply to the authors, they may release it under any terms they want). so no, it isn't free in case it would be interpreted as "must"; and if it doesn't mean "must", why emphasise the "written" and put it in the licensing terms in the first place? on similarity with Firefox: it may seem similar, but it's different. I agree that if osmAnd said "it's enough to rename it and replace the artwork", then it would be free; however, it says "this applies to the code", it says nothing on any rebranding. Ineiev (talk) 09:11, 27 November 2015 (UTC)
Ineiev is unquestionably correct. That said, maybe a patch can be proposed to them, adding something like "it's enough to rename it and replace the artwork", removing the word "exception" and mentioning the relevant article of GPLv3 which authorises the requirement (7d or 7e, I guess[1]). Nemo (talk) 11:09, 1 December 2015 (UTC)
It is free as long as it is distributed on for free. RicoZ (talk) 22:39, 4 December 2015 (UTC)
Talk:Android#osmAnd_licensing mentions the 10 free map download limit stuff. Anyway what a mess. I'll stay away from it. Jidanni (talk) 01:18, 6 December 2015 (UTC)
Opened to seek clarification. RicoZ (talk) 19:33, 5 December 2015 (UTC)
Thank you, they've actually updated the license to exclude the code from the "exception". Ineiev (talk) 09:42, 7 December 2015 (UTC)
It is still complicated but personally I am happy with the terms and trust the expertise of the crowds who are generally rather picky. Maybe the infobox should be updated to "GPLv3 with artwork and design elements CC-BY-ND-NC" ? RicoZ (talk) 12:41, 7 December 2015 (UTC)
I agree this still may be questionable. I'll try to discuss it with people. Thank you! Ineiev (talk) 13:06, 7 December 2015 (UTC)