[Nominatim] Add support for structured requests

[Persaeus]

For the Nominatim search API, the search term may be specified with two different sets of parameters:

• Free-form query string q; or
• Structured request parameters: street, city, county, state, country and postalcode.

We currently only support the free-form format. This PR adds support for structured requests:

$query = GeocodeQuery::create(' ')->withData('city', 'Las Vegas')->withData('state', 'Nevada');

Note that free-form format and structured request format cannot be combined. So, if structured requests parameters are given, we remove the q parameter.

[jbelien]

Thanks @nihilsen !

I get the idea but I really dislike the GeocodeQuery::create(' ') to be honest. So far, the library has been focused on address geocoding and it seems really counter intuitive to create a query with only a space.

What's your opinion on this @willdurand @Nyholm ?

[Persaeus]

I get the idea but I really dislike the GeocodeQuery::create(' ') to be honest

I was thinking the same. It's not ideal.

The idea is that whatever you put as the "query string" in the GeocodeQuery is irrelevant because it isn't used if any of the structured request parameters are specified. The client may still put something there as a fallback if no structured query parameters are provided:

$geocodeQuery = GeocodeQuery::create($_GET['q']);

if (isset($_GET['city'])) {
    $geocodeQuery = $geocodeQuery->withData('city', $_GET['city']);
}

[Persaeus]

I have another PR in mind for Nominatim which either builds on this PR or is a separate PR.

I will briefly summarize it here, so you see what my original motivation is for wanting this PR merged.

---

The idea is that you can supply "type" as query data, .e.g.:

$geocodeQuery::create('Paris')->withData('type', 'city');

This would be converted to a query-string like ?city=Paris.

This would be particularly useful for geocoding recursively with Nominatim.

While this could be implemented as a simple PR in its own right, I think it would be better implemented on top of this PR, as that would allow more expressive queries, e.g.:

$geocodeQuery::create('Las Vegas')->withData('type', 'city')->withData('state', 'Nevada');