GeocodeForward: geocode-glib Reference Manual

## GeocodeForward GeocodeForward — Geocode forward geocoding object |

## Functions

GeocodeForward * | geocode_forward_new_for_string ()
GeocodeForward * | geocode_forward_new_for_params ()
guint | geocode_forward_get_answer_count ()
void | geocode_forward_set_answer_count ()
GeocodeBoundingBox * | geocode_forward_get_search_area ()
void | geocode_forward_set_search_area ()
gboolean | geocode_forward_get_bounded ()
void | geocode_forward_set_bounded ()
void | geocode_forward_search_async ()
GList * | geocode_forward_search_finish ()
GList * | geocode_forward_search ()
void | geocode_forward_set_backend ()

## Properties

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

## Types and Values

struct | GeocodeForward
struct | GeocodeForwardClass

## 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.

Owner: GeocodeForward

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.

Owner: GeocodeForward

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.

Owner: GeocodeForward

Flags: Read / Write