GeocodeForward

GeocodeForward — Geocode forward geocoding object

Synopsis

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

struct              GeocodeForward;
struct              GeocodeForwardClass;
GeocodeForward *    geocode_forward_new_for_string      (const char *str);
GeocodeForward *    geocode_forward_new_for_params      (GHashTable *params);
guint               geocode_forward_get_answer_count    (GeocodeForward *forward);
void                geocode_forward_set_answer_count    (GeocodeForward *forward,
                                                         guint count);
GeocodeBoundingBox * geocode_forward_get_search_area    (GeocodeForward *forward);
void                geocode_forward_set_search_area     (GeocodeForward *forward,
                                                         GeocodeBoundingBox *box);
gboolean            geocode_forward_get_bounded         (GeocodeForward *forward);
void                geocode_forward_set_bounded         (GeocodeForward *forward,
                                                         gboolean bounded);
void                geocode_forward_search_async        (GeocodeForward *forward,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GList *             geocode_forward_search_finish       (GeocodeForward *forward,
                                                         GAsyncResult *res,
                                                         GError **error);
GList *             geocode_forward_search              (GeocodeForward *forward,
                                                         GError **error);
void                geocode_forward_set_backend         (GeocodeForward *forward,
                                                         GeocodeBackend *backend);

Object Hierarchy

  GObject
   +----GeocodeForward

Properties

  "answer-count"             guint                 : Read / Write
  "bounded"                  gboolean              : Read / Write
  "search-area"              GeocodeBoundingBox*   : Read / Write

Description

Contains functions for geocoding using the OSM Nominatim APIs

Details

struct GeocodeForward

struct GeocodeForward;

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


struct GeocodeForwardClass

struct GeocodeForwardClass {
};

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


geocode_forward_new_for_string ()

GeocodeForward *    geocode_forward_new_for_string      (const char *str);

Creates a new GeocodeForward to perform forward geocoding with. The string is in free-form format.

str :

a string containing a free-form description of the location

Returns :

a new GeocodeForward. Use g_object_unref() when done.

geocode_forward_new_for_params ()

GeocodeForward *    geocode_forward_new_for_params      (GHashTable *params);

Creates a new GeocodeForward to perform geocoding with. The GHashTable is in the format used by Telepathy, and documented on Telepathy's specification site.

See also: XEP-0080 specification.

params :

a GHashTable with string keys, and GValue values. [transfer none][element-type utf8 GValue]

Returns :

a new GeocodeForward. Use g_object_unref() when done.

geocode_forward_get_answer_count ()

guint               geocode_forward_get_answer_count    (GeocodeForward *forward);

Gets the number of requested results for searches.

forward :

a GeocodeForward representing a query

geocode_forward_set_answer_count ()

void                geocode_forward_set_answer_count    (GeocodeForward *forward,
                                                         guint count);

Sets the number of requested results to count.

forward :

a GeocodeForward representing a query

count :

the number of requested results, which must be greater than zero

geocode_forward_get_search_area ()

GeocodeBoundingBox * geocode_forward_get_search_area    (GeocodeForward *forward);

Gets the area to limit searches within.

forward :

a GeocodeForward representing a query

Returns :

the search area, or NULL if none is set. [transfer none][nullable]

geocode_forward_set_search_area ()

void                geocode_forward_set_search_area     (GeocodeForward *forward,
                                                         GeocodeBoundingBox *box);

Sets the area to limit searches within.

forward :

a GeocodeForward representing a query

box :

a bounding box to limit the search area.

geocode_forward_get_bounded ()

gboolean            geocode_forward_get_bounded         (GeocodeForward *forward);

Gets the "bounded" property that regulates whether the "search-area" property acts restricting or not.

forward :

a GeocodeForward representing a query

geocode_forward_set_bounded ()

void                geocode_forward_set_bounded         (GeocodeForward *forward,
                                                         gboolean bounded);

Set the "bounded" property that regulates whether the "search-area" property acts restricting or not.

forward :

a GeocodeForward representing a query

bounded :

TRUE to restrict results to only items contained within the "search-area" bounding box.

geocode_forward_search_async ()

void                geocode_forward_search_async        (GeocodeForward *forward,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously performs a forward geocoding query using a web service. Use geocode_forward_search() to do the same thing synchronously.

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

forward :

a GeocodeForward representing a query

cancellable :

optional GCancellable forward, NULL to ignore.

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

the data to pass to callback function

geocode_forward_search_finish ()

GList *             geocode_forward_search_finish       (GeocodeForward *forward,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes a forward geocoding operation. See geocode_forward_search_async().

forward :

a GeocodeForward representing a query

res :

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]

geocode_forward_search ()

GList *             geocode_forward_search              (GeocodeForward *forward,
                                                         GError **error);

Gets the result of a forward geocoding query using the current backend (see geocode_forward_set_backend()). By default the GNOME Nominatim server is used. See GeocodeBackend for more information.

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

forward :

a GeocodeForward representing a query

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]

geocode_forward_set_backend ()

void                geocode_forward_set_backend         (GeocodeForward *forward,
                                                         GeocodeBackend *backend);

Specifies the backend to use in the forward geocoding operation.

If none is given, the default GNOME Nominatim server is used.

forward :

a GeocodeForward representing a query

backend :

a GeocodeBackend, or NULL to use the default one. [nullable][transfer none]

Since 3.23.1

Property Details

The "answer-count" property

  "answer-count"             guint                 : Read / Write

The number of requested results to a search query.

Allowed values: <= G_MAXLONG

Default value: 10


The "bounded" property

  "bounded"                  gboolean              : Read / Write

If set to TRUE then only results in the "search-area" bounding box are returned. If set to FALSE the "search-area" is treated like a preferred area for results.

Default value: FALSE


The "search-area" property

  "search-area"              GeocodeBoundingBox*   : Read / Write

The bounding box that limits the search area. If "bounded" property is set to TRUE only results from this area is returned.