The library for determining GPS data for location objects. It can get GPS coordinates from address details such as town, county, country, etc. and vice versa. geocoder_docs for more info. More...

Data Structures
struct	Address
	A datatype for storing a postal address as well as its geographic coordinates if possible. More...

struct	Coordinate
	A datatype for storing a geographic coordinate. More...

struct	GeocoderTool
	A datatype that accesses an external geocoding provider to calculate the geographic data for an Address. More...

Functions
bool	DetermineGPSLocationForAddress (Address address_p, GeocoderTool tool_p, GrassrootsServer *grassroots_p)
	Determine the geographic coordinates for a given Address using a given GeocoderTool. More...

bool	DetermineAddressForGPSLocation (Address address_p, GeocoderTool tool_p, GrassrootsServer *grassroots_p)
	Determine the geographic coordinates for a given Address using a given GeocoderTool. More...

Address *	AllocateAddress (const char name_s, const char street_s, const char town_s, const char county_s, const char country_s, const char postcode_s, const char country_code_s, const char gps_s)
	Allocte a new Address object. More...

void	FreeAddress (Address *address_p)
	Free an Address. More...

void	ClearAddress (Address *address_p)
	Clear all of the values within an Address. More...

char *	GetAddressAsString (const Address *address_p)
	Get a string represetnting an Address. More...

char *	GetAddressAsDelimitedString (const Address address_p, const char sep_s)
	Get a string represetnting an Address. More...

json_t *	GetAddressAsJSON (const Address *address_p)
	Get the JSON representation of an Address. More...

Address *	GetAddressFromJSON (const json_t *address_json_p)
	Get a new Address from a JSON representation. More...

bool	ConvertAddressToJSON (const Address address_p, json_t dest_p)
	Store the JSON-based representation of an Address in a given JSON fragment. More...

bool	ParseAddressForSchemaOrg (const Address address_p, json_t values_p, const char *address_key_s)
	Populate a JSON fragment with the values from a given Address conforming to the definition of a postal address from schema.org given at https://schema.org/PostalAddress. More...

bool	SetAddressCentreCoordinate (Address address_p, const double64 latitude, const double64 longitude, const double64 elevation_p)
	Set the Coordinate for the central point of a given address to the given latitude and longitude values. More...

bool	SetAddressNorthEastCoordinate (Address address_p, const double64 latitude, const double64 longitude, const double64 elevation_p)
	Set the Coordinate for the north-east bounds of a given address to the given latitude and longitude values. More...

bool	SetAddressSouthWestCoordinate (Address address_p, const double64 latitude, const double64 longitude, const double64 elevation_p)
	Set the Coordinate for the south-west bounds of a given address to the given latitude and longitude values. More...

Coordinate *	AllocateCoordinate (double64 x, double64 y)
	Allocate a coordinate for a given latitude and longitude. More...

void	InitCoordinate (Coordinate *coord_p)
	Initialise a coordinate as 0,0. More...

void	FreeCoordinate (Coordinate *coord_p)
	Free a Coordinate. More...

json_t *	GetCoordinateAsJSON (const Coordinate *const coord_p)
	Get the JSON representation of a Coordinate. More...

bool	AddCoordinateToJSON (const Coordinate coord_p, json_t dest_p, const char *const coord_key_s)
	Add the JSON representation for a given Coordinate to a JSON fragment using a given key. More...

bool	SetCoordinateFromJSON (Coordinate coord_p, const json_t value_p)
	Set the Coordinate from a JSON representation. More...

bool	SetCoordinateElevation (Coordinate *coord_p, double64 elevation)
	Set the elevation for a given Coordinate. More...

void	ClearCoordinateElevation (Coordinate *coord_p)
	Clear the elevation for a given Coordinate. More...

Variables
const char *	AD_NAME_S = "name"
	The key for specifying an object containing the name of an address. More...

const char *	AD_POSTCODE_S = "postalCode"
	The key for specifying an object containing the postal code where the sample was collected. More...

const char *	AD_STREET_S = "streetAddress"
	The key for specifying an object containing the street address where the sample was collected. More...

const char *	AD_TOWN_S = "addressLocality"
	The key for specifying an object containing the town where the sample was collected. More...

const char *	AD_COUNTY_S = "addressRegion"
	The key for specifying an object containing the county where the sample was collected. More...

const char *	AD_COUNTRY_S = "addressCountry"
	The key for specifying an object containing the country where the sample was collected. More...

const char *	AD_LOCATION_S = "location"
	The key for the location object for a given record. More...

const char *	AD_CENTRE_LOCATION_S = "centre"
	The key for the central location object for a given record. More...

const char *	AD_NORTH_EAST_LOCATION_S = "north_east_bound"
	The key for the north-eastern bounds for the location object for a given record. More...

const char *	AD_SOUTH_WEST_LOCATION_S = "south_west_bound"
	The key for the south-western bounds for the location object for a given record. More...

const char *	CO_LATITUDE_S = "latitude"
	The key for the latitude of for a location object for a given record. More...

const char *	CO_LONGITUDE_S = "longitude"
	The key for the longitude of for a location object for a given record. More...

const char *	CO_ELEVATION_S = "elevation"
	The key for the elevation of for a location object for a given record. More...

Detailed Description

The library for determining GPS data for location objects. It can get GPS coordinates from address details such as town, county, country, etc. and vice versa. geocoder_docs for more info.

Function Documentation

◆ DetermineGPSLocationForAddress()

bool DetermineGPSLocationForAddress	(	Address *	address_p,
		GeocoderTool *	tool_p,
		GrassrootsServer *	grassroots_p
	)

Determine the geographic coordinates for a given Address using a given GeocoderTool.

Parameters

address_p	The Address to determine the GPS coordinates for.
tool_p	The GeocoderTool used to calculate the GPS coordinates for the given Address

Returns: true if the GPS location was calculated successfully, false otherwise.

◆ DetermineAddressForGPSLocation()

bool DetermineAddressForGPSLocation	(	Address *	address_p,
		GeocoderTool *	tool_p,
		GrassrootsServer *	grassroots_p
	)

Determine the geographic coordinates for a given Address using a given GeocoderTool.

Parameters

address_p	The Address whose GPS coordinates will be used.
tool_p	The GeocoderTool used to calculate the Address for the given GPS coordinates.

Returns: true if the Address was calculated successfully, false otherwise.

◆ AllocateAddress()

Address * AllocateAddress	(	const char *	name_s,
		const char *	street_s,
		const char *	town_s,
		const char *	county_s,
		const char *	country_s,
		const char *	postcode_s,
		const char *	country_code_s,
		const char *	gps_s
	)

Allocte a new Address object.

Parameters

name_s	The building name or number the new Address.
street_s	The street for the new Address.
town_s	The street for the new Address.
county_s	The town, city or village that the new Address is in.
country_s	The country that the new Address is in.
postcode_s	The postal code for the new Address.
country_code_s	The ISO 3166-1 alpha-2 country code for the country that this new Address is in.
gps_s	The string representation of the geographic coordinate for this Address such as "32.4567, 12.1234" for a latitude of 32.4567 degrees and a longitude of 12.1234 degrees. This can be `NULL`

Returns: The newly-allocated Address or NULL upon error.

◆ FreeAddress()

void FreeAddress ( Address * address_p )

Free an Address.

Parameters

address_p The Address to free.

◆ ClearAddress()

void ClearAddress ( Address * address_p )

Clear all of the values within an Address.

Parameters

address_p The Address to clear.

◆ GetAddressAsString()

char * GetAddressAsString ( const Address * address_p )

Get a string represetnting an Address.

Parameters

address_p The Address to get the JSON representation for.

Returns: The newly-allocated string representing the Address or NULL upon error.

◆ GetAddressAsDelimitedString()

char * GetAddressAsDelimitedString	(	const Address *	address_p,
		const char *	sep_s
	)

Get a string represetnting an Address.

Parameters

address_p The Address to get the JSON representation for.

Returns: The newly-allocated string representing the Address or NULL upon error.

◆ GetAddressAsJSON()

json_t * GetAddressAsJSON ( const Address * address_p )

Get the JSON representation of an Address.

This calls ConvertAddressToJSON() on a newly-allocated JSON object.

Parameters

address_p The Address to get the JSON representation for.

Returns: The JSON representation or NULL upon error.

◆ GetAddressFromJSON()

Address * GetAddressFromJSON ( const json_t * address_json_p )

Get a new Address from a JSON representation.

Parameters

address_json_p The JSON representation of the Address to create.

Returns: The newly-allocated Address or NULL upon error.

◆ ConvertAddressToJSON()

bool ConvertAddressToJSON	(	const Address *	address_p,
		json_t *	dest_p
	)

Store the JSON-based representation of an Address in a given JSON fragment.

Parameters

address_p	The address to get the value from.
dest_p	The JSON fragment where the values for the given Address will be stored.

Returns: true if the Address was converted successfully, false otherwise.

◆ ParseAddressForSchemaOrg()

bool ParseAddressForSchemaOrg	(	const Address *	address_p,
		json_t *	values_p,
		const char *	address_key_s
	)

Populate a JSON fragment with the values from a given Address conforming to the definition of a postal address from schema.org given at https://schema.org/PostalAddress.

Parameters

address_p	The Address to get the values from.
values_p	The JSON fragment to add the JSON-based representation of the given Address to
address_key_s	The key that will be used in values_p to add the JSON-based representation for.

Returns: true if the details for the Address were added successfully, false otherwise.

◆ SetAddressCentreCoordinate()

bool SetAddressCentreCoordinate	(	Address *	address_p,
		const double64	latitude,
		const double64	longitude,
		const double64 *	elevation_p
	)

Set the Coordinate for the central point of a given address to the given latitude and longitude values.

Parameters

address_p	The Address to set the central point for.
latitude	The latitude, in degrees, of the central point to set for the given Address.
longitude	The longitude, in degrees, of the central point to set for the given Address.
elevation_p	A pointer to the elevation value, in metres, for the given Address. This can be `NULL` if the elevation is unknown. A copy of the value is stored so this pointer does not need to stay in scope.

Returns: true if the Coordinate was set successfully, false otherwise.

◆ SetAddressNorthEastCoordinate()

bool SetAddressNorthEastCoordinate	(	Address *	address_p,
		const double64	latitude,
		const double64	longitude,
		const double64 *	elevation_p
	)

Set the Coordinate for the north-east bounds of a given address to the given latitude and longitude values.

Parameters

address_p	The Address to set the south-west bounds for.
latitude	The latitude, in degrees, of the north-east bounds to set for the given Address.
longitude	The longitude, in degrees, of the north-east bounds to set for the given Address.
elevation_p	A pointer to the elevation value, in metres, for the given Address. This can be `NULL` if the elevation is unknown. A copy of the value is stored so this pointer does not need to stay in scope.

Returns: true if the Coordinate was set successfully, false otherwise.

◆ SetAddressSouthWestCoordinate()

bool SetAddressSouthWestCoordinate	(	Address *	address_p,
		const double64	latitude,
		const double64	longitude,
		const double64 *	elevation_p
	)

Set the Coordinate for the south-west bounds of a given address to the given latitude and longitude values.

Parameters

address_p	The Address to set the south-west bounds for.
latitude	The latitude, in degrees, of the south-west bounds to set for the given Address.
longitude	The longitude, in degrees, of the south-west bounds to set for the given Address.
elevation_p	A pointer to the elevation value, in metres, for the given Address. This can be `NULL` if the elevation is unknown. A copy of the value is stored so this pointer does not need to stay in scope.

Returns: true if the Coordinate was set successfully, false otherwise.

◆ AllocateCoordinate()

Coordinate * AllocateCoordinate	(	double64	x,
		double64	y
	)

Allocate a coordinate for a given latitude and longitude.

Parameters

x	The latitude to use.
y	The longitude to use.

Returns: The new Coordinate or NULL upon error.

◆ InitCoordinate()

void InitCoordinate ( Coordinate * coord_p )

Initialise a coordinate as 0,0.

Parameters

coord_p The Coordinate to initialise.

◆ FreeCoordinate()

void FreeCoordinate ( Coordinate * coord_p )

Free a Coordinate.

Parameters

coord_p The Coordinate to free.

◆ GetCoordinateAsJSON()

json_t * GetCoordinateAsJSON ( const Coordinate *const coord_p )

Get the JSON representation of a Coordinate.

Parameters

coord_p The Coordinate to get the JSON representation for.

Returns: The JSON representation or NULL upon error.

◆ AddCoordinateToJSON()

bool AddCoordinateToJSON	(	const Coordinate *	coord_p,
		json_t *	dest_p,
		const char *const	coord_key_s
	)

Add the JSON representation for a given Coordinate to a JSON fragment using a given key.

The value added for the Coordinate is derived using SetCoordinateFromJSON().

Parameters

coord_p	The Coordinate to add to the JSON fragment.
dest_p	The JSON fragment to add the Coordinate's JSON to.
coord_key_s	The key used to add the Coordinate's JSON to the given JSON fragment.

Returns: true if the Coordinate was added successfully, false otherwise.

◆ SetCoordinateFromJSON()

bool SetCoordinateFromJSON	(	Coordinate *	coord_p,
		const json_t *	value_p
	)

Set the Coordinate from a JSON representation.

Parameters

coord_p	The Coordinate to set the values for.
The	JSON representation to get the values from.

Returns: true if the Coordinate was set successfully, false otherwise.

◆ SetCoordinateElevation()

bool SetCoordinateElevation	(	Coordinate *	coord_p,
		double64	elevation
	)

Set the elevation for a given Coordinate.

Parameters

coord_p	The Coordinate to set the elevation for.
elevation	The elevation value to set for the given Coordinate.

Returns: true if the Coordinate's elevation was set successfully, false otherwise.

◆ ClearCoordinateElevation()

void ClearCoordinateElevation ( Coordinate * coord_p )

Clear the elevation for a given Coordinate.

Parameters

coord_p The Coordinate to clear the elevation for.

Variable Documentation

◆ AD_NAME_S

const char* AD_NAME_S = "name"

The key for specifying an object containing the name of an address.

◆ AD_POSTCODE_S

const char* AD_POSTCODE_S = "postalCode"

The key for specifying an object containing the postal code where the sample was collected.

◆ AD_STREET_S

const char* AD_STREET_S = "streetAddress"

The key for specifying an object containing the street address where the sample was collected.

For example the house number and street name.

◆ AD_TOWN_S

const char* AD_TOWN_S = "addressLocality"

The key for specifying an object containing the town where the sample was collected.

◆ AD_COUNTY_S

const char* AD_COUNTY_S = "addressRegion"

The key for specifying an object containing the county where the sample was collected.

◆ AD_COUNTRY_S

const char* AD_COUNTRY_S = "addressCountry"

The key for specifying an object containing the country where the sample was collected.

◆ AD_LOCATION_S

const char* AD_LOCATION_S = "location"

The key for the location object for a given record.

◆ AD_CENTRE_LOCATION_S

const char* AD_CENTRE_LOCATION_S = "centre"

The key for the central location object for a given record.

◆ AD_NORTH_EAST_LOCATION_S

const char* AD_NORTH_EAST_LOCATION_S = "north_east_bound"

The key for the north-eastern bounds for the location object for a given record.

◆ AD_SOUTH_WEST_LOCATION_S

const char* AD_SOUTH_WEST_LOCATION_S = "south_west_bound"

The key for the south-western bounds for the location object for a given record.

◆ CO_LATITUDE_S

const char* CO_LATITUDE_S = "latitude"

The key for the latitude of for a location object for a given record.

◆ CO_LONGITUDE_S

const char* CO_LONGITUDE_S = "longitude"

The key for the longitude of for a location object for a given record.

◆ CO_ELEVATION_S

const char* CO_ELEVATION_S = "elevation"

The key for the elevation of for a location object for a given record.

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ DetermineGPSLocationForAddress()

◆ DetermineAddressForGPSLocation()

◆ AllocateAddress()

◆ FreeAddress()

◆ ClearAddress()

◆ GetAddressAsString()

◆ GetAddressAsDelimitedString()

◆ GetAddressAsJSON()

◆ GetAddressFromJSON()

◆ ConvertAddressToJSON()

◆ ParseAddressForSchemaOrg()

◆ SetAddressCentreCoordinate()

◆ SetAddressNorthEastCoordinate()

◆ SetAddressSouthWestCoordinate()

◆ AllocateCoordinate()

◆ InitCoordinate()

◆ FreeCoordinate()

◆ GetCoordinateAsJSON()

◆ AddCoordinateToJSON()

◆ SetCoordinateFromJSON()

◆ SetCoordinateElevation()

◆ ClearCoordinateElevation()

Variable Documentation

◆ AD_NAME_S

◆ AD_POSTCODE_S

◆ AD_STREET_S

◆ AD_TOWN_S

◆ AD_COUNTY_S

◆ AD_COUNTRY_S

◆ AD_LOCATION_S

◆ AD_CENTRE_LOCATION_S

◆ AD_NORTH_EAST_LOCATION_S

◆ AD_SOUTH_WEST_LOCATION_S

◆ CO_LATITUDE_S

◆ CO_LONGITUDE_S

◆ CO_ELEVATION_S