GeocodeForward

GeocodeForward — Geocode forward geocoding object

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── GeocodeForward

Includes

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

Description

Contains functions for geocoding using the

OSM Nominatim APIs

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

forward

a GeocodeForward representing a query

 

backend

a GeocodeBackend, or NULL to use the default one.

[nullable][transfer none]

Since: 3.23.1

Types and Values

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.

Property Details

The “answer-count” property

  “answer-count”             guint

The number of requested results to a search query.

Flags: Read / Write

Allowed values: <= G_MAXINT

Default value: 10


The “bounded” property

  “bounded”                  gboolean

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.

Flags: Read / Write

Default value: FALSE


The “search-area” property

  “search-area”              GeocodeBoundingBox *

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

Flags: Read / Write