GeocodeNominatim: geocode-glib Reference Manual

## GeocodeNominatim GeocodeNominatim — Geocoding resolver using a Nominatim web service |

## Functions

GeocodeNominatim * | geocode_nominatim_new ()
GeocodeNominatim * | geocode_nominatim_get_gnome ()

## Properties

gchar * | base-url | Read / Write / Construct Only
gchar * | maintainer-email-address | Read / Write / Construct Only
gchar * | user-agent | Read / Write

## Types and Values

#define | GEOCODE_TYPE_NOMINATIM
struct | GeocodeNominatimClass
| GeocodeNominatim

## Object Hierarchy

        GObject
        ╰── GeocodeNominatim

## Implemented Interfaces

GeocodeNominatim implements GeocodeBackend.

## Includes

    #include <geocode-glib/geocode-glib.h>

## Description

Contains functions for geocoding using the OSM Nominatim APIs exposed by a Nominatim server at a given URI. By default, the GNOME Nominatim server is used, but other server details may be given when constructing a GeocodeNominatim.

## Functions

### geocode_nominatim_new ()

    GeocodeNominatim *
    geocode_nominatim_new (const gchar *base_url,
                           const gchar *maintainer_email_address);

Creates a new backend implementation for an online Nominatim server. See the documentation for “base-url” and “maintainer-email-address”.

#### Parameters

base_url | a the base URL of the Nominatim server. |
maintainer_email_address | the email address of the software maintainer. |

#### Returns

a new GeocodeNominatim. Use `g_object_unref()` when done.

[transfer full]

Since: 3.23.1

### geocode_nominatim_get_gnome ()

    GeocodeNominatim *
    geocode_nominatim_get_gnome (void);

Gets a reference to the default Nominatim server on nominatim.gnome.org.

This function is thread-safe.

#### Returns

a new GeocodeNominatim. Use `g_object_unref()` when done.

[transfer full]

Since: 3.23.1

## Types and Values

### GEOCODE_TYPE_NOMINATIM

    #define GEOCODE_TYPE_NOMINATIM (geocode_nominatim_get_type ())

See GeocodeNominatim.

Since: 3.23.1

### struct GeocodeNominatimClass

    struct GeocodeNominatimClass {
    	GObjectClass parent_class;

    	gchar *(*query)        (GeocodeNominatim    *self,
    	                        const gchar         *uri,
    	                        GCancellable        *cancellable,
    	                        GError             **error);

    	void   (*query_async)  (GeocodeNominatim    *self,
    	                        const gchar         *uri,
    	                        GCancellable        *cancellable,
    	                        GAsyncReadyCallback  callback,
    	                        gpointer             user_data);

    	gchar *(*query_finish) (GeocodeNominatim    *self,
    	                        GAsyncResult        *res,
    	                        GError             **error);
    };

GeocodeNominatim allows derived classes to override its query functions, which are called for each network request the Nominatim client makes. All network requests are `GET`s with no request body; just a URI. The default implementation makes the requests internally, but derived classes may want to override these queries to check the URIs for testing, for example.

Applications should not normally have to derive GeocodeNominatim; these virtual methods are mainly intended for testing.

#### Members

`query` () | synchronous query function to override network `GET` requests. |
`query_async` () | asynchronous version of `query` . |
`query_finish` () | asynchronous finish function for `query_async` . |

Since: 3.23.1

### GeocodeNominatim

    typedef struct _GeocodeNominatim GeocodeNominatim;

All the fields in the GeocodeNominatim structure are private and should never be accessed directly.

Since: 3.23.1

## Property Details

### The `“base-url”` property

      “base-url”                 gchar *

The base URL of the Nominatim service, for example `https://nominatim.example.org`.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.23.1

### The `“maintainer-email-address”` property

      “maintainer-email-address” gchar *

E-mail address of the maintainer of the software making the geocoding requests to the Nominatim server. This is used to contact them in the event of a problem with their usage. See the Nominatim API.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.23.1

### The `“user-agent”` property

      “user-agent”               gchar *

User-Agent string to send with HTTP(S) requests, or `NULL` to use the default user agent, which is derived from the geocode-glib version and “id”, for example: `geocode-glib/3.20 (MyAppId)`.

As per the Nominatim usage policy, it should be set to a string which identifies the application which is using geocode-glib, and must be a valid user agent string.

Flags: Read / Write

Default value: NULL

Since: 3.23.1