Constructing query in Nominatim

Question

I wonder how to construct the structured query URL for the OSM Nominatim? According to the documentation, one can use the free-form-query or the structured-query. This is the base url https://nominatim.openstreetmap.org/search?<params>.

The search term may be specified with two different sets of parameters:

q=<query>

Free-form query string to search for. Free-form queries are processed first left-to-right and then right-to-left if that fails. So you may search for pilkington avenue, birmingham as well as for birmingham, pilkington avenue. Commas are optional, but improve performance by reducing the complexity of the search.

street=<housenumber> <streetname>
city=<city>
county=<county>
state=<state>
country=<country>

postalcode=<postalcode>

Alternative query string format split into several parameters for structured requests. Structured requests are faster but are less robust against alternative OSM tagging schemas. Do not combine with q= parameter.

With the free-form-query, I construct the URL like this

https://nominatim.openstreetmap.org/search?q=pilkington avenue,birmingham&format=json

But how would I construct the URL with the structured query? If I do it like this

https://nominatim.openstreetmap.org/search?street=pilkington avenue,city=birmingham&format=json

I get no results!

Answer 1

In a url query, the parameters need to be separated by '&'

thus, the comma between 'avenue' and 'city' should be replaced by a '&':

https://nominatim.openstreetmap.org/search?street=pilkington avenue&city=birmingham&format=json

Additionally, if you manually put this in the browser, your browser should automatically url-encode the spaces and other characters that require it, but if you are doing this programmatically then you will need to encode them using a function. For example with JavaScript you would use encodeURI('https://nominatim.openstreetmap.org/search?street=pilkington avenue&city=birmingham&format=json') and the output would be :

https://nominatim.openstreetmap.org/search?street=pilkington%20avenue&city=birmingham&format=json

If you put this in your browser, you will see that it gives some results.