====== Location With or Without GPS ======

ViziApps has high-accuracy GPS capability that couldn't be easier to use: simply include the GPS field in any page, and then reference its latitude and longitude fields to get the data. 

However, there are situations where an alternative to high-accuracy GPS is important:
  * A GPS signal can sometimes take several minutes for lock-on, or it may fail completely.
  * The user may have GPS disabled (in privacy options). 
  * It may be far more important to get a quick lock on location, even at lower accuracy. 
  * Using GPS consumes battery power, so some applications are better optimized for low power than high-accuracy location.
  * The GPS field isn't available for testing in App Preview or within Web Apps.
  * Privacy restrictions demand that the exact user location is not obtained nor disclosed.

Examples for needing quick but low-accuracy location reporting include: 
  * location-based searches (e.g. **[[http://auth.viziapps.mobi/wiki/searching_with_google_places|Searching With Google Places]]**)
  * showing local news or weather
  * including the general vicinity of a user's position for a report.

The ViziApps Quick Location JavaScript library addresses these issues. It requires a small amount of JavaScript coding to incorporate this library into your app. You would use this library instead of the standard GPS field.

<WRAP tip>
You can look for the **[[quick_start|template app]]** called **Google Places and Maps** to see the following examples in action.
</WRAP>

===== Setup the Library =====

Install the ViziApps JavaScript library into your app's HTML Header. 

<code>
<script src="https://s3.amazonaws.com/viziapps/apps/quick_location_1.0.0.js"></script>

<script>
// create an instance of the quick location api:
var quickloc = new v.quickLocation();

$( document ).ready(function() {
    // make first call to get location
    quickloc.get();
});
</script>
</code>

===== Get Location =====

Use the **.get()** method to find the current location. Process the success or failure results with the **[[http://api.jquery.com/category/deferred-object/|jQuery Deferred Methods]]** **.done()** and **.fail()**. 

<code>
function whereAmI()
{
    quickloc.get()
    .done( function( myLocation )
    {
        v.setFieldValue( 'lastUpdateField', new Date( myLocation.timestamp ) );
        v.setFieldValue( 'myLocationField', myLocation.lat + ', ' + myLocation.lng );
        v.setFieldValue( 'myDirectionField', myLocation.heading + ' degrees, ' + myLocation.speed + ' m/s' );
        v.setFieldValue( 'locAccuracyField', myLocation.accuracy );
    })
    .fail( function( errorMessage )
    {
        alert( 'Location error: ' + errorMessage );
    });
}
</code>

===== Stopping the Service =====

The Quick Location library will continue to monitor the user's location to ensure that location reports are not too old. You can turn off this monitoring service with the **.stop()** method.
<code>
// start the location service:
quickloc.get();
// stop the location service:
quickloc.stop();
</code>

===== Low-Power Operation =====

You can constrain the Quick Location library to use only low-accuracy, low-power location services by setting the **.lowPower** property.
<code>
quickloc.lowPower = true;
quickloc.get();
</code>

===== How It Works =====

The Quick Location library will first make an attempt to use cellular network location methods which are very fast but have low accuracy. After the first location reading is returned, the library will attempt to use high-resolution GPS so that subsequent calls to the **.get()** method may find higher accuracy results. When both a cellular network and GPS are unavailable, the Quick Location library will use the **[[http://www.hostip.info/|hostip]]** web service. The library should always return a location value that is less than five minutes old - otherwise an error is returned.