The Geocoding Module

The library for determining GPS data for location objects. 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...
 
AddressAllocateAddress (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...
 
AddressGetAddressFromJSON (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...
 
CoordinateAllocateCoordinate (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_GPS_S = "GPS"
 The key for specifying an object containing the GPS coordinates where the sample was collected. More...
 
const char * AD_POSTCODE_S = "Postal code"
 The key for specifying an object containing the postal code where the sample was collected. More...
 
const char * AD_STREET_S = "Street"
 The key for specifying an object containing the street address where the sample was collected. More...
 
const char * AD_TOWN_S = "Town"
 The key for specifying an object containing the town where the sample was collected. More...
 
const char * AD_COUNTY_S = "County"
 The key for specifying an object containing the county where the sample was collected. More...
 
const char * AD_COUNTRY_S = "Country"
 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_pThe Address to determine the GPS coordinates for.
tool_pThe 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_pThe Address whose GPS coordinates will be used.
tool_pThe 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_sThe building name or number the new Address.
street_sThe street for the new Address.
town_sThe street for the new Address.
county_sThe town, city or village that the new Address is in.
country_sThe country that the new Address is in.
postcode_sThe postal code for the new Address.
country_code_sThe ISO 3166-1 alpha-2 country code for the country that this new Address is in.
gps_sThe 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_pThe Address to free.

◆ ClearAddress()

void ClearAddress ( Address address_p)

Clear all of the values within an Address.

Parameters
address_pThe Address to clear.

◆ GetAddressAsString()

char * GetAddressAsString ( const Address address_p)

Get a string represetnting an Address.

Parameters
address_pThe 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_pThe 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_pThe 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_pThe 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_pThe address to get the value from.
dest_pThe 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_pThe Address to get the values from.
values_pThe JSON fragment to add the JSON-based representation of the given Address to
address_key_sThe 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_pThe Address to set the central point for.
latitudeThe latitude, in degrees, of the central point to set for the given Address.
longitudeThe longitude, in degrees, of the central point to set for the given Address.
elevation_pA 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_pThe Address to set the south-west bounds for.
latitudeThe latitude, in degrees, of the north-east bounds to set for the given Address.
longitudeThe longitude, in degrees, of the north-east bounds to set for the given Address.
elevation_pA 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_pThe Address to set the south-west bounds for.
latitudeThe latitude, in degrees, of the south-west bounds to set for the given Address.
longitudeThe longitude, in degrees, of the south-west bounds to set for the given Address.
elevation_pA 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
xThe latitude to use.
yThe 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_pThe Coordinate to initialise.

◆ FreeCoordinate()

void FreeCoordinate ( Coordinate coord_p)

Free a Coordinate.

Parameters
coord_pThe Coordinate to free.

◆ GetCoordinateAsJSON()

json_t * GetCoordinateAsJSON ( const Coordinate *const  coord_p)

Get the JSON representation of a Coordinate.

Parameters
coord_pThe 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_pThe Coordinate to add to the JSON fragment.
dest_pThe JSON fragment to add the Coordinate's JSON to.
coord_key_sThe 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_pThe Coordinate to set the values for.
TheJSON 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_pThe Coordinate to set the elevation for.
elevationThe 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_pThe Coordinate to clear the elevation for.

Variable Documentation

◆ AD_GPS_S

const char* AD_GPS_S = "GPS"

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

◆ AD_POSTCODE_S

const char* AD_POSTCODE_S = "Postal code"

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

◆ AD_STREET_S

const char* AD_STREET_S = "Street"

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 = "Town"

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

◆ AD_COUNTY_S

const char* AD_COUNTY_S = "County"

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

◆ AD_COUNTRY_S

const char* AD_COUNTRY_S = "Country"

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.