map::geocode::nominatim(n)

💖 map::geocode::nominatim 💖

okay bestie, listen — this is the manual page for map::geocode::nominatim(n), like, the Tcl manual page from the Mapping utilities corner of the universe, and we are going to get you fluent in it in one sitting. no cap. it's lowkey just "ask a Nominatim server where a place is" and honestly? iconic. 🗺️✨

---

🌸 NAME 🌸

map::geocode::nominatim — the way you resolve geographical names by talking to a Nominatim service. it's giving "type a city name, get coordinates back." 💅

---

🎀 SYNOPSIS 🎀

package require Tcl 8.6 9

package require http

package require json

package require uri

package require snit

package require map::geocode::nominatim ?0.3?

::map::geocode::nominatim requestor ?-baseurl url? ?-callback  callback?
?-error error callback?

$cmdprefix result

$cmdprefix errorstring

requestor search query

look at all those package require lines — yes you need Tcl 8.6 9, http, json, uri, snit, and then map::geocode::nominatim ?0.3? itself. assemble the whole squad before you start, fr fr. 🫶

---

✨ DESCRIPTION ✨

so this package hands you a class for accessing geocoding services that implement the Nominatim interface. (the actual details of that interface live in References, scroll down babe, it's right there. 👇)

---

👑 API 👑

::map::geocode::nominatim requestor ?-baseurl url? ?-callback callback?
?-error error callback?

creates a geocoding request object named requestor, and this little guy is the one that will be sliding its requests over to the Nominatim server. main character energy, honestly. 💫

the result of the command is name. periodt.

💅 OPTIONS 💅

• -baseurl url — the base URL of the Nominatim service you're hitting up. the default is OpenStreetMap's service at http://nominatim.openstreetmap.org/search. and ooh, a possible free alternative lives at http://open.mapquestapi.com//nominatim/v1/search — yes, that double slash is in there, don't touch it, it's part of the vibe. 🙈
• -callback cmdprefix — a command prefix that gets invoked the moment search results become available. if you don't set anything when you create the object, the default kicks in and just prints the result (see below) to stdout. the result of the command prefix is ignored, bestie, we don't care about it. and if the command prefix throws an error? it gets caught, and that triggers the error callback (that's the -error option, keep reading 👀), with the error message as the argument.

the signature of the command prefix is:

$cmdprefix result

and result is a list of dictionaries, one item per hit. each dictionary is carrying these entries:

• place_id — the place ID. (FIXME: what's this? genuinely, the original says this, we're all confused together 😭)
• licence — the data licence string.
• osm_type — the OSM type of the location.
• osm_id — FIXME.
• boundingbox — the coordinates of the bounding box (min and max latitude, min and max longitude).
• lat — the location's latitude.
• lon — the location's longitude.
• display_name — the location's human readable name. 🥰
• class — FIXME.
• type — FIXME.
• icon — FIXME.

• -error cmdprefix — a command prefix to invoke when you run into errors. typically these are HTTP errors, like, the server said no. 🚫 if you don't specify one when creating the object, the default is to print the errorstring (see below) to stderr. the result of the command prefix is ignored. and if the command prefix itself throws an error? those get passed to higher levels — no catching, no hiding, straight up the chain. 💀

the signature of the command prefix is:

$cmdprefix errorstring

🦋 METHODS 🦋

• requestor search query — this method returns a list of dictionaries, one item per hit, for the query you specified. that's it, that's the whole thing, and it's perfect. 🌈

---

⭐ REFERENCES ⭐

1. http://wiki.openstreetmap.org/wiki/Nominatim
2. http://open.mapquestapi.com/nominatim/

go read those if you want the deep lore, iykyk. 📚

---

🍓 KEYWORDS 🍓

geocoding, http, location, map, nominatim, server, url

---

heads up bestie: the FIXME notes above are in the original page, so they're staying in this one. that's not me being lazy, that's me being faithful. 💖

---

and that's the whole page, babe! this one came from tcllib, version 0.3, and it's map::geocode::nominatim(n) through and through. slay, go geocode something, and remember: the bounding box knows all four of its corners. 🌸🦋💜