Add namespace (fix #3)

[yohanboniface]

See #3. @sgillies sounds OK for you? (The diff is a bit messed up, dunno why :/)

[yohanboniface]

cc @cquest @christophlingg @randymeech

[dianashk]

@yohanboniface, thanks for putting this spec together! I think it makes a lot of sense and we plan to use it for Pelias responses if possible.

The namespacing is definitely a needed enhancement.

I'm wondering if we should namespace address, as you're already doing with admin. The thinking is to allow clients to easily specify which blocks they want to include/exclude in the response. Basically, grouping the following properties:

{
  "geocoding": {
     "address" : {
        "housenumber": "64",
        "street": "Rue de Metz",
        "postcode": "59280",
        "city": "Armentières",
        "district": null,
        "county": null,
        "state": null,
        "country": "France"
    },
    "admin": {
       // ...
    }
  }
}

label and name should stay outside of address.

So in API requests you can do something like:

\search?query=64 Rue de Metz&properties=label,address

What do you think?

[yohanboniface]

I'm wondering if we should namespace address, as you're already doing with admin.

(re #8 too ;) ) I'm wondering if we are not going too much the namespace way, and losing the simplicity. I'm not against your suggestion about address, just openly sharing my own doubts ;)

The thinking is to allow clients to easily specify which blocks they want to include/exclude in the response.

Is it really a use case we need to cover? I guess you are thinking about making the geojson smaller?

[yohanboniface]

One more thing I'm thinking of: I agree that being able to define which properties will be returned can be a nice feature that should not clash with this spec, but then grouping some data into address seems to be a bit arbitrary, and thus, for example, doesn't allow to only request for say housenumber and street (this could be a real scenario: I'm requesting for geocoding of hundreds of houses in the same city, I may only need the housenumber and street, given that everything else is the same for all results). In other words, at this time, I don't see a strong argument to break the simplicity of having a flat structure inside geocoding. But I'm open to be convinced I'm missing a good argument ;)

[dianashk]

Oops, just realized I mislabeled the address namespace with geocoder in my example JSON above. Sorry, will fix.

@yohanboniface I understand your desire to keep things simple and clean. My perspective on this spec is very closely tied to geocoder API design since this is tightly coupled with a geocoder. So with that in mind, having the ability to control the level of detail coming back from your query is important. Geocoder API clients are very diverse, as I'm sure you're aware. :weary:

but then grouping some data into address seems to be a bit arbitrary,

Grouping those particular items isn't arbitrary. It's based on thinking through the typical usecases of geocoder clients. There are those that want just the label, already formatted and ready to be displayed. Then others want address, with all the parts broken out, and admin. With that said, my suggested address grouping might not be the best grouping, so I'm totally fine with refining that further.

and thus, for example, doesn't allow to only request for say housenumber and street (this could be a real scenario: I'm requesting for geocoding of hundreds of houses in the same city, I may only need the housenumber and street, given that everything else is the same for all results).

You can still reference each item within the address block using address.street. In fact supporting that structure allows you to group additional properties in the future in a similar way. For example, when dealing with boundary results, we often have to return back all the various translated name:* properties. It would be nice to have the ability to group them all under name.

I guess we could also argue that the structure within geocoder doesn't need to be specified by the spec? Different countries name their admin values differently. Some havehousenameand other parts ofhousenumberlike fractions and letters. Maybe it's enough to just say use thegeocoding` namespace, and the rest is geocoder-specific. I don't personally like that route, because I'd love for clients to be able to swap out geocoders with ease, which is the whole purpose of having a spec such as this. But I think it's still worth bringing up for discussion.

[yohanboniface]

Grouping those particular items isn't arbitrary. It's based on thinking through the typical usecases of geocoder clients. There are those that want just the label, already formatted and ready to be displayed. Then others want address, with all the parts broken out, and admin. With that said, my suggested address grouping might not be the best grouping, so I'm totally fine with refining that further.

Why not just letting people do /search/?q=xxxx&properties=housenumber,street,city?

[dianashk]

Why not just letting people do /search/?q=xxxx&properties=housenumber,street,city?

Just ends up being more verbose.

[yohanboniface]

Just ends up being more verbose.

But keeps the spec simpler ;) I'm merging here, let's continue the discussion on #8.