GeocodeLocation: geocode-glib Reference Manual

## GeocodeLocation GeocodeLocation — Geocode location object |

## Functions

GeocodeLocation * | geocode_location_new ()
GeocodeLocation * | geocode_location_new_with_description ()
gboolean | geocode_location_equal ()
gboolean | geocode_location_set_from_uri ()
char * | geocode_location_to_uri ()
double | geocode_location_get_distance_from ()
void | geocode_location_set_description ()
const char * | geocode_location_get_description ()
gdouble | geocode_location_get_latitude ()
gdouble | geocode_location_get_longitude ()
gdouble | geocode_location_get_altitude ()
GeocodeLocationCRS | geocode_location_get_crs ()
gdouble | geocode_location_get_accuracy ()
guint64 | geocode_location_get_timestamp ()

## Properties

double | accuracy | Read / Write
double | altitude | Read / Write
GeocodeLocationCRS | crs | Read / Write / Construct Only
char * | description | Read / Write
double | latitude | Read / Write
double | longitude | Read / Write
guint64 | timestamp | Read / Write / Construct Only

## Types and Values

struct | GeocodeLocation
struct | GeocodeLocationClass
enum | GeocodeLocationURIScheme
enum | GeocodeLocationCRS
#define | GEOCODE_LOCATION_ALTITUDE_UNKNOWN
#define | GEOCODE_LOCATION_ACCURACY_UNKNOWN
#define | GEOCODE_LOCATION_ACCURACY_STREET
#define | GEOCODE_LOCATION_ACCURACY_CITY
#define | GEOCODE_LOCATION_ACCURACY_REGION
#define | GEOCODE_LOCATION_ACCURACY_COUNTRY
#define | GEOCODE_LOCATION_ACCURACY_CONTINENT

## Object Hierarchy

        GObject
        ╰── GeocodeLocation

## Includes

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

## Description

The GeocodeLocation instance represents a location on earth, with an optional description.

## Functions

### geocode_location_new ()

    GeocodeLocation *
    geocode_location_new (gdouble latitude,
                          gdouble longitude,
                          gdouble accuracy);

Creates a new GeocodeLocation object.

#### Parameters

latitude | a valid latitude |
longitude | a valid longitude |
accuracy | accuracy of location in meters |

#### Returns

a new GeocodeLocation object. Use `g_object_unref()` when done.

### geocode_location_new_with_description ()

    GeocodeLocation *
    geocode_location_new_with_description (gdouble latitude,
                                           gdouble longitude,
                                           gdouble accuracy,
                                           const char *description);

Creates a new GeocodeLocation object.

#### Parameters

latitude | a valid latitude |
longitude | a valid longitude |
accuracy | accuracy of location in meters |
description | a description for the location |

#### Returns

a new GeocodeLocation object. Use `g_object_unref()` when done.

### geocode_location_equal ()

    gboolean
    geocode_location_equal (GeocodeLocation *a,
                            GeocodeLocation *b);

Compare two GeocodeLocation instances for equality. This compares all fields and only returns `TRUE` if the instances are exactly equal. For example, if both locations have the same physical coordinates, but one location has its “description” property set and the other does not, `FALSE` will be returned. Similarly, if both locations have the same “latitude”, “longitude” and “altitude”, but a different “accuracy” or “timestamp”, `FALSE` will be returned. Or if both locations have the same“latitude” and “longitude” but a different “altitude”, `FALSE` will be returned.

Both instances must be non-`NULL`.

#### Parameters

a | a location |
b | another location |

#### Returns

`TRUE` if the instances are equal, `FALSE` otherwise

Since: 3.23.1

### geocode_location_set_from_uri ()

    gboolean
    geocode_location_set_from_uri (GeocodeLocation *loc,
                                   const char *uri,
                                   GError **error);

Initialize a GeocodeLocation object with the given `uri` .

The URI should be in the geo scheme (RFC 5870) which in its simplest form looks like:

- geo:latitude,longitude

An Android extension to set a description is also supported in the form of:

- geo:0,0?q=latitude,longitude(description)

#### Parameters

loc | a GeocodeLocation |
uri | a URI mapping out a location |
error | GError for error reporting, or `NULL` to ignore |

#### Returns

`TRUE` on success and `FALSE` on error.

### geocode_location_to_uri ()

    char *
    geocode_location_to_uri (GeocodeLocation *loc,
                             GeocodeLocationURIScheme scheme);

Creates a URI representing `loc` in the scheme specified in `scheme` .

#### Parameters

loc | a GeocodeLocation |
scheme | the scheme of the requested URI |

#### Returns

a URI representing the location. The returned string should be freed with `g_free()` when no longer needed.

### geocode_location_get_distance_from ()

    double
    geocode_location_get_distance_from (GeocodeLocation *loca,
                                        GeocodeLocation *locb);

Calculates the distance in km, along the curvature of the Earth, between 2 locations. Note that altitude changes are not taken into account.

#### Parameters

loca | a GeocodeLocation |
locb | a GeocodeLocation |

#### Returns

a distance in km.

### geocode_location_set_description ()

    void
    geocode_location_set_description (GeocodeLocation *loc,
                                      const char *description);

Sets the description of `loc` to `description` .

#### Parameters

loc | a GeocodeLocation |
description | a description for the location |

### geocode_location_get_description ()

    const char *
    geocode_location_get_description (GeocodeLocation *loc);

Gets the description of location `loc` .

#### Parameters

loc | a GeocodeLocation |

#### Returns

The description of location `loc` .

### geocode_location_get_latitude ()

    gdouble
    geocode_location_get_latitude (GeocodeLocation *loc);

Gets the latitude of location `loc` .

#### Parameters

loc | a GeocodeLocation |

#### Returns

The latitude of location `loc` .

### geocode_location_get_longitude ()

    gdouble
    geocode_location_get_longitude (GeocodeLocation *loc);

Gets the longitude of location `loc` .

#### Parameters

loc | a GeocodeLocation |

#### Returns

The longitude of location `loc` .

### geocode_location_get_altitude ()

    gdouble
    geocode_location_get_altitude (GeocodeLocation *loc);

Gets the altitude of location `loc` .

#### Parameters

loc | a GeocodeLocation |

#### Returns

The altitude of location `loc` .

### geocode_location_get_crs ()

    GeocodeLocationCRS
    geocode_location_get_crs (GeocodeLocation *loc);

Gets the Coordinate Reference System Identification of location `loc` .

#### Parameters

loc | a GeocodeLocation |

#### Returns

The CRS of location `loc` .

### geocode_location_get_accuracy ()

    gdouble
    geocode_location_get_accuracy (GeocodeLocation *loc);

Gets the accuracy (in meters) of location `loc` .

#### Parameters

loc | a GeocodeLocation |

#### Returns

The accuracy of location `loc` .

### geocode_location_get_timestamp ()

    guint64
    geocode_location_get_timestamp (GeocodeLocation *loc);

Gets the timestamp (in seconds since the Epoch) of location `loc` . See “timestamp”.

#### Parameters

loc | a GeocodeLocation |

#### Returns

The timestamp of location `loc` .

## Types and Values

### struct GeocodeLocation

    struct GeocodeLocation;

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

### struct GeocodeLocationClass

    struct GeocodeLocationClass {
    };

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

### enum GeocodeLocationURIScheme

The URI scheme for this location.

#### Members

GEOCODE_LOCATION_URI_SCHEME_GEO | The 'geo' URI scheme, RFC 5870 |

### enum GeocodeLocationCRS

Coordinate Reference System Identification for a location.

#### Members

GEOCODE_LOCATION_CRS_WGS84 | CRS is World Geodetic System, standard for Earth. |

### GEOCODE_LOCATION_ALTITUDE_UNKNOWN

    #define GEOCODE_LOCATION_ALTITUDE_UNKNOWN -G_MAXDOUBLE

Constant representing unknown altitude.

### GEOCODE_LOCATION_ACCURACY_UNKNOWN

    #define GEOCODE_LOCATION_ACCURACY_UNKNOWN -1

Constant representing unknown accuracy.

### GEOCODE_LOCATION_ACCURACY_STREET

    #define GEOCODE_LOCATION_ACCURACY_STREET 1000 /* 1 km */

Constant representing street-level accuracy.

### GEOCODE_LOCATION_ACCURACY_CITY

    #define GEOCODE_LOCATION_ACCURACY_CITY 15000 /* 15 km */

Constant representing city-level accuracy.

### GEOCODE_LOCATION_ACCURACY_REGION

    #define GEOCODE_LOCATION_ACCURACY_REGION 50000 /* 50 km */

Constant representing region-level accuracy.

### GEOCODE_LOCATION_ACCURACY_COUNTRY

    #define GEOCODE_LOCATION_ACCURACY_COUNTRY 300000 /* 300 km */

Constant representing country-level accuracy.

### GEOCODE_LOCATION_ACCURACY_CONTINENT

    #define GEOCODE_LOCATION_ACCURACY_CONTINENT 3000000 /* 3000 km */

Constant representing continent-level accuracy.

## Property Details

### The `“accuracy”` property

      “accuracy”                 double

The accuracy of this location in meters.

Owner: GeocodeLocation

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“altitude”` property

      “altitude”                 double

The altitude of this location in meters.

Owner: GeocodeLocation

Flags: Read / Write

Default value: -1.79769e+308

### The `“crs”` property

      “crs”                      GeocodeLocationCRS

The Coordinate Reference System Identification of this location. Only the value 'wgs84' is currently valid.

Owner: GeocodeLocation

Flags: Read / Write / Construct Only

Default value: GEOCODE_LOCATION_CRS_WGS84

### The `“description”` property

      “description”              char *

The description of this location.

Owner: GeocodeLocation

Flags: Read / Write

Default value: NULL

### The `“latitude”` property

      “latitude”                 double

The latitude of this location in degrees.

Owner: GeocodeLocation

Flags: Read / Write

Allowed values: [-90,90]

Default value: 0

### The `“longitude”` property

      “longitude”                double

The longitude of this location in degrees.

Owner: GeocodeLocation

Flags: Read / Write

Allowed values: [-180,180]

Default value: 0

### The `“timestamp”` property

      “timestamp”                guint64

A timestamp in seconds since

Epoch,

giving when the location was resolved from an address.

A value of 0 (zero) will be interpreted as the current time.

Owner: GeocodeLocation

Flags: Read / Write / Construct Only

Allowed values: <= G_MAXINT64

Default value: 0