There is a Pelias leaflet plugin which serves as a good demo: http://pelias.github.io/leaflet-geocoder/#12/40.7258/-73.980...

Working on a better one that highlights all the levers in the API :)

Yeah, I have the same confusion. I tried with just raw API calls, http://pelias.mapzen.com/search?input=Stockholm, but the "demo" seems like it would be more useful.