API stability? whazzat?

November 10, 2007

I haven’t posted in a while, so some news first: I’ve joined the OpenedHand crew. So far it’s been great: interesting projects, smart people and a really nice and telework-approving atmosphere (I had some doubts about working several thousand kilometers and two timezones away from the office, but it’s been very smooth so far).

For the past few days Iain Holmes and I have been reviewing the geoclue API (for those of you just tuning in: Geoclue is a geoinformation framework/library that’ll make your apps location-aware, whether on desktop, laptop or Internet Tablet). Iain posted our proposal to the mailing list yesterday. Comments on the API changes are very welcome, especially from application developers interested in using Geoclue.

I feel like I should explain why we want to change pretty much the whole API — I know it might look like NIH syndrome if you just take a quick look… So here goes:

  • First, we’re still unreleased*: if we want to change something, now is the time.
  • The way functionality was divided among interfaces did not make sense to us: One data provider may provide position, but not address info; another may provide both. It makes sense that the first one implements Position-interface and the second one implements both Position and Address. These changes will make it easier to write a master-server that could actually select different data sources based on their availability and accuracy
  • A few methods and signals had details that really needed to be changed: CivicLocation did not have timestamp on it. Position didn’t have real validity flags so it was hard to tell if a result was valid coordinate or not.
  • At this point the milk had been spilled already. The API had to break in a major way anyway, so there’s little harm in fixing the small annoyances too: CamelCasing interface, method and signal names; changing method names to more meaningful ones (like CivicLocation -> Address).

*) I do have geoclue packages available for maemo, but they’re not widely used yet, as far as I can tell. I promise to help if someone’s done a lot of work based on current API.

6 Responses to “API stability? whazzat?”

  1. Simon Pickering Says:

    I’ve just read the geoclue-developers post and follow ups and see that the very fine grained position accuracy has been removed from Geoclue.Address:

    “We also removed the incredibly fine grained building
    name, floor and room number, as we didn’t think many services would be that accurate.”

    Although I don’t yet know much about Geoclue, I disagree with this removal; if a company/individual had enough wifi access points (for example), it would be quite easy to do building, floor and possibly even room location. With future technologies then who knows how fine grained one could go. You are designing an API that will be used into the future after all.

  2. jku Says:

    Hi Simon, thanks for the comment. I’m a bit undecided myself (the original Address-interface was my work after all).

    The problem is that at the moment we have no data sources that would provide resolution like that… and more importantly I feel that we just don’t know enough to get the data fields correct at this time. In other words there’s a good chance that if we add a Building-name field it would be left unused and people would actually want another (yet unknown) data field…

    I guess I’d like to wait and see A) what kind of data we’ll be likely to get from data sources and B) what kind of data applications would like to have… There’s still the text-field that can be used for unstructured data in the mean time.

    btw, please comment on the mailing list too — this is something I’m not 100% sure myself.

  3. […] API stability? whazzat? “I haven’t posted in a while, so some news first: I’ve joined the OpenedHand crew.” — Jussi Kukkonen has joined OpenedHand, and is hacking on Geoclue with Iain. Geoclue + Gypsy = ROCK! (tags: jussikukkonen openedhand gnome mobile gmae geoclue gypsy) […]

  4. R. G. Newbury Says:

    I’m still waiting for my ‘developer-discount’ N810 to arrive at the store, but I’m starting to plan on how to develope the nav package I am thinking about.
    One nit on your API..’Geoclue.Velocity’ “direction” should really be called ‘bearing’…( 0 to 360 *true*) as that is what most GPS units deliver. (“Climb” could be called ‘rate’ but I think most people will understand).

    Any reason why in GeoClue.Position it is not called ‘SetPosition’? I presume that this method is intended to ‘push’ a waypoint to the hardware. “PositionChanged” is ambiguous.

    Any reason why the methods in GeoClue.Position and GeoClue.Velocity do not follow NMEA sentence output structures? All GPS units can output in that format (Garmin has their own format as well). The sentences are well understood and there is no apparent reason why the info the unit provides should be dropped…(For example NMEA sentence GGA provides more data than Geoclue.Position.

    I also note that there is no mention of the datum being used..If you are attempting to match an external map source to a GPS input, the datum is absolutely necessary..including an error routine from when they don’t. I read somewhere that the Clark datum used on South African maps is hundreds of metres different horizontally and vertically from the WGS84 datum. And the GGA sentence includes a local correction figure for geoid sea level to WGS84 datum.

  5. jku Says:

    Hello R. G. Newbury,

    The general design principle was “be generic, be usable”. Being generic means that GPS is not our only data source. Being usable means we try to look at this like an application developer would: we expect geoclue to be used in a wide variety of apps (most of which will _not_ be geoinfo apps in the traditional sense), and tried to make the API as unsurprising as possible from that POV.

    I believe you are correct about bearing/direction.

    The whole API is for client apps, so GetPosition will tell the client the current position as it is known to the Position provider (e.g. a gpsd-provider). NMEA is not used because it’s A) not generic and B) not really known to anyone outside the GPS developers’ small circle. Remember that we’re not trying to write a gps daemon here (although Iain’s working on that elsewhere: http://gypsy.freedesktop.org/index.html :)).

    About datum: API is WGS84 and we expect data sources to be that also. So far, I’ve seen no exceptions. If a data source is not WGS84 the provider/backend for that data source must convert before emitting the position to clients.

  6. R. G. Newbury Says:

    OK. I misunderstood the ‘direction’ of data-flow. So this is a ‘middle-ware’ API to translate data from eg a gps daemon, to a client-side app…Cool.

    NMEA is pretty generic. There are about a dozen types of hardware, each with a whack of ‘sentences’. Lots of them actually pass the same sort of data (speed, for example) but the source is part of the data (so that the meaning can be better understood). And since many units only export NMEA, you will have to translate those…

    Following my misunderstanding of the direction of data flow, there really should be a ‘Set.Position’ to mirror ‘Get.Position’. So the client app can input a waypoint to the hardware. One thing small GPS units cannot do (well), is input arbitrary waypoints. You can generally easily say ‘Make *here* a waypoint’, but it is very hard to input ‘Make 43.36’48” N 79.20’12” W a waypoint’. That is where the client app can help.

    Regarding datum, maybe there should be an API to call for the NMEA sentence which contains the reported datum
    GGDTM… and raise a flag if not WGS84 (allowing a plugin to further translate the data???).

    Any thoughts on adding API calls to output data sets, eg to Mysql/sqlite etc?

    Just thinking out loud.. And still waiting for my new toy.. All I want for Christmas is my N810…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: