User Guide

Synapse-Nominatim User Guide

Synapse-Nominatim adds new Storm commands to allow you to query a Nominatim endpoint.

Getting Started

Check with your Admin to enable permissions.

Examples

Adding your personal API endpoint

By default Synapse-Nominatim will use the global config when defined. Users can override this by adding a personal endpoint. To configure a personal endpoint:

> nominatim.config.add myuser "https://mydeployment:10089" --scope self
Synapse-Nominatim config "myuser" added

nominatim.enrich and nominatim.search will now use the new myuser config over the global config. Note: to override the config on a per-search, per-enrich basis you can supply the --config switch to the command. See the help for examples of this.

Enriching Nodes Using Nominatim

Enrich nodes supporting :loc with nominatim.enrich and yield the results:

> inet:ipv4=1.2.3.4 | nominatim.enrich --yield
geo:place=12d36171409ee802b473b9e33ff502df
        .created = 2024/11/19 21:25:21.924
        :address = london bridge, the queens walk, bermondsey village, the borough, london borough of southwark, london, greater london, england, se1 9bg, united kingdom
        :bbox = -0.0883452,-0.0870196,51.5067548,51.5092817
        :latlong = 51.50804895,-0.08767154999999874
        :loc = gb.england.london
        :name = london bridge
        :type = nominatim.bridge

Searching with Nominatim

Search takes a free-form query string to search for. Results from the search are used to create geo:place nodes.

> nominatim.search "Denver International Airport" --yield
geo:place=c6ae04d56b8b22a5d84bfbeaeb7cb7ff
        .created = 2024/11/19 21:25:22.105
        :address = denver international airport, 8500, peña boulevard, denver, colorado, 80249, united states
        :bbox = -104.7376124,-104.6078734,39.8174181,39.9042141
        :latlong = 39.8606676,-104.68536732610298
        :loc = us.colorado.denver
        :name = denver international airport
        :type = nominatim.aerodrome
geo:place=0d66ba7db260af23ca04b3d25d942163
        .created = 2024/11/19 21:25:22.170
        :address = denver international airport, peña boulevard, denver, colorado, united states
        :bbox = -104.7409596,-104.7408596,39.8340229,39.8341229
        :latlong = 39.8340729,-104.7409096
        :loc = us.colorado.denver
        :name = denver international airport
        :type = nominatim.information

Use of `meta:source` nodes

Synapse-Nominatim uses meta:source nodes and -(seen)> light weight edges to track nodes observed from the Nominatim API.

The meta:source iden is derived from the configured API URL used when querying the Nominatim API endpoints. These meta:source nodes have the type property set to synapse.nominatim.

Storm can be used to filter nodes to include/exclude nodes which have been observed by Synapse-Nominatim. The following example shows how to filter the results of a query to include only results observed by Synapse-Nominatim:

> #cool.tag.lift +{ <(seen)- meta:source +:type=synapse.nominatim }