haiku/docs/user/shared/Geolocation.dox

/*
 * Copyright 2019 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Adrien Destugues, pulkomandy@pulkomandy.tk
 * 
 * Corresponds to:
 *		headers/private/shared/Geolocation.h	hrev53611
 *		src/kits/shared/Geolocation.cpp			hrev53613S
 */


/*!
	\file Geolocation.h
	\ingroup shared
	\brief Geolocation and geocoding services.
*/


/*!
	\class BGeolocation
	\ingroup shared
	\brief Geolocation and geocoding services.

	Geolocation allows to know where the computer is currently located.
	This is currently done by sending a list of Wifi networks within reach to
	a 3rd party webservice (Mozilla location services), which uses a database
	of known networks around the world to return an estimate position.

	Geocoding is about identifying places in a way more convenient than
	latitude and longitude. This can include postal codes, country names,
	street or building names, etc. This class allows to perform both geocoding
	(finding a latitude and a longitude from a name) and reverse geocoding
	(finding a suitable name for a given position). This service is provided
	to haiku by the 3rd-party geonames.org

	Note that most of the methods in this class perform HTTPS requests to
	3rd-parties. When using it in your application, it is good practise to
	first inform the user about what will be shared with these services, and
	why that's needed. Of course, this also means using these services requires
	internet access, and you may want to limit the number of calls, both to
	save bandwidth and time, and to not overuse the provided API keys. If you
	are going to do more than a few request per application run, you should
	provide your own API keys instead.

	\since Haiku R1
*/


/*!
	\fn BGeolocation::BGeolocation()
	\brief Initialize a BGeolocation using the default services and API keys.

	Official builds of Haiku include a shared API key for both Mozilla Location
	Services and geonames.org. You can use this constructor to use these keys
	in your application.
*/


/*!
	\fn BGeolocation::BGeolocation(const BUrl& geolocationService,
		const BUrl& geocodingService)
	\brief Initialize a BGeolocation using custom services or API keys.

	You can use this constructor to provide your own URL to a webservice to
	use for the requests. The services have to implement the MLS and geonames
	API, respectively.

	If you want to override only one of the two URLs, the other can be passed
	as an empty BUrl object.
*/


/*!
	\fn status_t BGeolocation::LocateSelf(float& latitude, float& longitude)
	\brief Locate the computer by detecting nearby WiFi networks.

	This method makes a request to Mozilla Location Services.
*/


/*!
	\fn status_t BGeolocation::Country(float latitude, float longitude,
		BCountry& country)
	\brief Find which country a given set of coordinates is in.

	This method makes a request to geonames.org.
*/