GeocodeBackend: geocode-glib Reference Manual

## GeocodeBackend GeocodeBackend — Geocode backend object |

## Functions

void | geocode_backend_forward_search_async ()
GList * | geocode_backend_forward_search_finish ()
GList * | geocode_backend_forward_search ()
void | geocode_backend_reverse_resolve_async ()
GList * | geocode_backend_reverse_resolve_finish ()
GList * | geocode_backend_reverse_resolve ()

## Types and Values

#define | GEOCODE_TYPE_BACKEND
struct | GeocodeBackendInterface
| GeocodeBackend

## Object Hierarchy

        GInterface
        ╰── GeocodeBackend

## Prerequisites

GeocodeBackend requires GObject.

## Known Implementations

GeocodeBackend is implemented by GeocodeMockBackend and GeocodeNominatim.

## Includes

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

## Description

The GeocodeBackend interface defines the operations that a resolver service must implement.

geocode-glib supports multiple backends which provide the underlying geocoding database and functionality. By default, the GeocodeNominatim backend is used with GNOME’s Nominatim server. If you are using geocode-glib in some GNOME software, this is the correct backend to use. Otherwise, you should use a new GeocodeNominatim instance with your own Nominatim server, or a custom GeocodeBackend implementation to use geocoding data from a non-Nominatim service. In all cases, please respect the terms of use of the service you are using.

If you are writing a library which uses geocode-glib, consider exposing the choice of GeocodeBackend in your library API, so that applications can make the best choice about which geocoding backend to use.

Custom backends can be implemented by subclassing GeocodeBackend and implementing the synchronous `forward_search` and `reverse_resolve` methods. The asynchronous versions may be implemented as well; the default implementations run the synchronous version in a thread.

In order to use a custom backend, either instantiate the backend directly and do forward and reverse queries on it using the GeocodeBackend interface; or create GeocodeForward and GeocodeReverse objects as normal, and set the backend they use with `geocode_forward_set_backend()` and `geocode_reverse_set_backend()`. They default to using the GNOME Nominatim backend.

GeocodeMockBackend is intended to be used in unit tests for applications which use geocode-glib — it allows them to set the geocode results they expect their application to query, and check afterwards that the queries were performed. Additionally, it works offline, which allows application unit tests to be run on integration and build machines which are not online. It is not expected that GeocodeMockBackend will be used in production code.

## Functions

### geocode_backend_forward_search_async ()

    void
    geocode_backend_forward_search_async (GeocodeBackend *backend,
                                          GHashTable *params,
                                          GCancellable *cancellable,
                                          GAsyncReadyCallback callback,
                                          gpointer user_data);

Asynchronously performs a forward geocoding query using the `backend` . Use `geocode_backend_forward_search()` to do the same thing synchronously.

The `params` hash table is in the format used by Telepathy, and documented in the Telepathy specification.

See also: XEP-0080 specification.

When the operation is finished, `callback` will be called. You can then call `geocode_backend_forward_search_finish()` to get the result of the operation.

#### Parameters

backend | a GeocodeBackend. |
params | a GHashTable with string keys, and GValue values. | [transfer none][element-type utf8 GValue]
cancellable | optional GCancellable, `NULL` to ignore. |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to the `callback` function |

Since: 3.23.1

### geocode_backend_forward_search_finish ()

    GList *
    geocode_backend_forward_search_finish (GeocodeBackend *backend,
                                           GAsyncResult *result,
                                           GError **error);

Finishes a forward geocoding operation. See `geocode_backend_forward_search_async()`.

#### Parameters

backend | a GeocodeBackend. |
result | a GAsyncResult. |
error | a GError. |

#### Returns

A list of places or `NULL` in case of errors. Free the returned instances with `g_object_unref()` and the list with `g_list_free()` when done.

[element-type GeocodePlace][transfer full]

Since: 3.23.1

### geocode_backend_forward_search ()

    GList *
    geocode_backend_forward_search (GeocodeBackend *backend,
                                    GHashTable *params,
                                    GCancellable *cancellable,
                                    GError **error);

Gets the result of a forward geocoding query using the `backend` .

If no results are found, a `GEOCODE_ERROR_NO_MATCHES` error is returned.

This is a synchronous function, which means it may block on network requests. In most situations, the asynchronous version (`geocode_backend_forward_search_async()`) is more appropriate. See its documentation for more information on usage.

#### Parameters

backend | a GeocodeBackend. |
params | a GHashTable with string keys, and GValue values. | [transfer none][element-type utf8 GValue]
cancellable | optional GCancellable, `NULL` to ignore. |
error | a GError |

#### Returns

A list of places or `NULL` in case of errors. Free the returned instances with `g_object_unref()` and the list with `g_list_free()` when done.

[element-type GeocodePlace][transfer full]

Since: 3.23.1

### geocode_backend_reverse_resolve_async ()

    void
    geocode_backend_reverse_resolve_async (GeocodeBackend *backend,
                                           GHashTable *params,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Asynchronously gets the result of a reverse geocoding query using the backend.

Typically, a single result will be returned representing the place at a given latitude and longitude (the `lat` and `lon` keys to `params` ); but in some cases the results will be ambiguous and *multiple* results will be returned. They will be returned in order of relevance, with the most relevant result first in the list.

The `params` hash table is in the format used by Telepathy, and documented in the Telepathy specification.

See also: XEP-0080 specification.

Use `geocode_backend_reverse_resolve()` to do the same thing synchronously.

When the operation is finished, `callback` will be called. You can then call `geocode_backend_reverse_resolve_finish()` to get the result of the operation.

#### Parameters

backend | a GeocodeBackend. |
params | a GHashTable with string keys, and GValue values. | [transfer none][element-type utf8 GValue]
cancellable | optional GCancellable object, `NULL` to ignore. |
callback | a GAsyncReadyCallback to call when the request is satisfied. |
user_data | the data to pass to callback function. |

Since: 3.23.1

### geocode_backend_reverse_resolve_finish ()

    GList *
    geocode_backend_reverse_resolve_finish
                                   (GeocodeBackend *backend,
                                    GAsyncResult *result,
                                    GError **error);

Finishes a reverse geocoding operation. See `geocode_backend_reverse_resolve_async()`.

#### Parameters

backend | a GeocodeBackend. |
result | a GAsyncResult. |
error | a GError. |

#### Returns

A list of GeocodePlace instances, or `NULL` in case of errors. The list is ordered by relevance, with most relevant results first. Free the returned instances with `g_object_unref()` and the list with `g_list_free()` when done.

[transfer full][element-type GeocodePlace]

Since: 3.23.1

### geocode_backend_reverse_resolve ()

    GList *
    geocode_backend_reverse_resolve (GeocodeBackend *backend,
                                     GHashTable *params,
                                     GCancellable *cancellable,
                                     GError **error);

Gets the result of a reverse geocoding query using the `backend` .

If no result could be found, a `GEOCODE_ERROR_NOT_SUPPORTED` error will be returned. This typically happens if the coordinates to geocode are in the middle of the ocean.

This is a synchronous function, which means it may block on network requests. In most situations, the asynchronous version, `geocode_backend_forward_search_async()`, is more appropriate. See its documentation for more information on usage.

#### Parameters

backend | a GeocodeBackend. |
params | a GHashTable with string keys, and GValue values. | [transfer none][element-type utf8 GValue]
cancellable | optional GCancellable object, `NULL` to ignore. |
error | a GError. |

#### Returns

A list of GeocodePlace instances, or `NULL` in case of errors. The list is ordered by relevance, with most relevant results first. Free the returned instances with `g_object_unref()` and the list with `g_list_free()` when done.

[transfer full][element-type GeocodePlace]

Since: 3.23.1

## Types and Values

### GEOCODE_TYPE_BACKEND

    #define GEOCODE_TYPE_BACKEND (geocode_backend_get_type ())

See GeocodeBackend.

Since: 3.23.1

### struct GeocodeBackendInterface

    struct GeocodeBackendInterface {
    	/* Forward */
    	GList        *(*forward_search)          (GeocodeBackend       *backend,
    	                                          GHashTable           *params,
    	                                          GCancellable         *cancellable,
    	                                          GError              **error);
    	void          (*forward_search_async)    (GeocodeBackend       *backend,
    	                                          GHashTable           *params,
    	                                          GCancellable         *cancellable,
    	                                          GAsyncReadyCallback   callback,
    	                                          gpointer              user_data);
    	GList        *(*forward_search_finish)   (GeocodeBackend       *backend,
    	                                          GAsyncResult         *result,
    	                                          GError              **error);

    	/* Reverse */
    	GList        *(*reverse_resolve)         (GeocodeBackend       *backend,
    	                                          GHashTable           *params,
    	                                          GCancellable         *cancellable,
    	                                          GError              **error);
    	void          (*reverse_resolve_async)   (GeocodeBackend       *backend,
    	                                          GHashTable           *params,
    	                                          GCancellable         *cancellable,
    	                                          GAsyncReadyCallback   callback,
    	                                          gpointer              user_data);
    	GList        *(*reverse_resolve_finish)  (GeocodeBackend       *backend,
    	                                          GAsyncResult         *result,
    	                                          GError              **error);
    };

Interface which defines the basic operations for geocoding.

#### Members

`forward_search` () | handles a synchronous forward geocoding request. |
`forward_search_async` () | starts an asynchronous forward geocoding request. |
`forward_search_finish` () | finishes an asynchronous forward geocoding request. |
`reverse_resolve` () | handles a synchronous reverse geocoding request. |
`reverse_resolve_async` () | starts an asynchronous reverse geocoding request. |
`reverse_resolve_finish` () | finishes an asynchronous reverse geocoding request. |

Since: 3.23.1

### GeocodeBackend

    typedef struct _GeocodeBackend GeocodeBackend;

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

Since: 3.23.1