Using geolocation

  • Revision slug: en/Using_geolocation
  • Revision title: Using geolocation
  • Revision id: 354121
  • Criado:
  • Criador: ronaldo.ap.abreu
  • É a revisão atual? Não
  • Comentar

Conteúdo da revisão

O Firefox 3.5 e versões superiores o Geolocation API, o qual permite que o usuário forneça sua localização para aplicações web, se assim o desejar. Por razões de privacidade, o usuário é solicitado a confirmar a permissão para relatar informações de localização.

O Firefox 3.5 inclui suporte para localizá-lo com base nas informações da sua rede Wi-Fi usando o Serviço Localização da Google (Google Location Services). Na comunicação entre o Firefox 3.5 e Google, os dados são trocados incluindo dados de acesso do Acess Point WiFi , um código token de acesso (semelhante a um cookie de duas semanas) e o endereço de IP do usuário. Para mais informações, por favor consulte a Politica de Provacidade da Mozilla e Politica de Privacidade da Google que cobrem como estes dados podem ser utilizados. Veja também o codigo fonte se você está curioso como este serviço é implementado.

Note: If your interest is in writing a geolocation provider -- a service which can be queried for the user's location -- please see {{ Interface("nsIGeolocationProvider") }}.  You may also find the WiFi access point monitoring service interesting.

O Firefox 3.6 (Gecko 1.9.2) adicionou suporte usando o GPSD (GPS daemon) serviço de Geolocalização do Linux.

Note: Extensions hosted on addons.mozilla.org must explicitly request permission before accessing geolocation data.

O objeto geolocation

O aplicativo de geolocalização é utilizado através de um objeto filho chamado geolocation localizado dentro do objeto navigator.  Se o objeto existe, os serviços de geolocalização estarão disponíveis. Você pode adicionalmente testar a presença da geolocalização:

if ("geolocation" in navigator) {
  /* geolocation is available */
} else {
  alert("I'm sorry, but geolocation services are not supported by your browser.");
}

{{ gecko_minversion_header("1.9.2") }}

Ao iniciar no Gecko 1.9.2 (Firefox 3.6), add-ons podem obter o objeto de geolocalização obtendo a referência para o serviço de geolocaliazação como se ve a seguir:

var geolocation = Components.classes["@mozilla.org/geolocation;1"]
                            .getService(Components.interfaces.nsIDOMGeoGeolocation);

Obtendo a posição atual

Para obter a localização atual do usuário, você pode utiliza o método getCurrentPosition().  Isto inicia uma requisição assíncrona para identificar a posição do usuário, e consulta ohardware de localizaçãopara conseguir informações atualizadas. Quando a posição é determinada, uma rotina específica de retorno é executada. Você pode opcionalmente gerar uma segunda rotina de retorno se um erro ocorrer.  Um terceiro, e opcional, parâmetro é a interface "opções" onde você pode configurar o tempo máximo da posição recebida e o tempo a se esperar por uma solicitação.

Use getCurrentPosition() se você deseja uma única posição rapidamente, independente da precisão.  Dispositivos com GPS, por exemplo, podem levar um minuto ou mais para conseguir a localização, e portanto dados menos precisos (localizxação do IP location ou rede wifi) podem retornar do método getCurrentPosition().

navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

O exemplo acima irá fazer a função the do_something() executar quando a localização for obtida.

Verificando a posição atual

If the position data changes (either by device movement or if more accurate geo information arrives) , you can set up a callback that is called with that updated position information.  This is done using the watchPosition() function, which has the same input parameters as getCurrentPosition().  Its callback is called multiple times, allowing the browser to either update your location as you move, or provide a more accurate location as different techniques are used to geolocate you.  The error callback, which is optional just as it is for getCurrentPosition(), is called only once, if there will never be valid results returned.

You can use watchPosition() without an initial getCurrentPosition() call.

var watchID = navigator.geolocation.watchPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
}
);

The watchPosition() method returns an ID number that can be used to uniquely identify the requested position watcher; you use this value in tandem with the clearWatch() method to stop watching the user's location.

navigator.geolocation.clearWatch(watchID);

watchPosition() accepts a success callback and error callback (like getCurrentPosition) and an optional positionObjects object, which can have three properties:

  • enableHighAccuracy – A boolean which indicates to the device that you wish to obtain it’s most accurate readings (this parameter may or may not make a difference, depending on your hardware)
  • maximumAge – The maximum age (in milliseconds) of the reading (this is appropriate as the device may cache readings to save power and/or bandwidth)
  • timeout – The maximum time (in milliseconds) for which you are prepared to allow the device to try to obtain a Geo location

A call to watchPosition could look like:

var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});

A demo of watchPosition in use: http://www.thedotproduct.org/experiments/geo/


Describing a position

The user's location is described using a Position object, which has the following fields:

timestamp
The time at which the reading was taken, as a DOMTimeStamp.
coords
An nsIDOMGeoPositionCoords object indicating the location.
address {{ gecko_minversion_inline("1.9.2") }} {{obsolete_inline("14.0")}}
An {{ interface("nsIDOMGeoPositionAddress") }} object specifying the corresponding address, if available.

Handling errors

The error callback, if provided when calling getCurrentPosition() or watchPosition(), has the following signature:

function errorCallback(PositionError error);

The PositionError structure has the following fields:

code
A numeric error code which much be one of the following:
UNKNOWN_ERROR (numeric value 0)
The location acquisition process failed due to an error not covered by the definition of any other error code in this interface.
PERMISSION_DENIED (numeric value 1)
The location acquisition process failed because the application origin does not have permission to use the Geolocation API.
POSITION_UNAVAILABLE (numeric value 2)
The position of the device could not be determined. One or more of the location providers used in the location acquisition process reported an internal error that caused the process to fail entirely.
TIMEOUT (numeric value 3)
The specified maximum length of time has elapsed before the implementation could successfully acquire a new Position object.
 
message
A human readable error message, suitable for use in logs and debugging -- but not for display to the user.

Browser compatibility

Browser Basic support Geolocation Level 2
Internet Explorer IE9 RC ---
Firefox (Gecko) 3.5 (1.9.1) ---
Opera 10.60 ---
Safari | Chrome | WebKit 5 | 5 | 533 ---

Prompting for permission

Any add-on hosted on addons.mozilla.org which makes use of geolocation data must explicitly request permission before doing so. The following function will request permission in a manner similar to the automatic prompt displayed for web pages. The user's response will be saved in the preference specified by the pref parameter, if applicable. The function provided in the callback parameter will be called with a boolean value indicating the user's response. If true, the add-on may access geolocation data.

function prompt(window, pref, message, callback) {
    let branch = Components.classes["@mozilla.org/preferences-service;1"]
                           .getService(Components.interfaces.nsIPrefBranch);

    if (branch.getPrefType(pref) === branch.PREF_STRING) {
        switch (branch.getCharPref(pref)) {
        case "always":
            return callback(true);
        case "never":
            return callback(false);
        }
    }

    let done = false;

    function remember(value, result) {
        return function() {
            done = true;
            branch.setCharPref(pref, value);
            callback(result);
        }
    }

    let self = window.PopupNotifications.show(
        window.gBrowser.selectedBrowser,
        "geolocation",
        message,
        "geo-notification-icon",
        {
            label: "Share Location",
            accessKey: "S",
            callback: function(notification) {
                done = true;
                callback(true);
            }
        }, [
            {
                label: "Always Share",
                accessKey: "A",
                callback: remember("always", true)
            },
            {
                label: "Never Share",
                accessKey: "N",
                callback: remember("never", false)
            }
        ], {
            eventCallback: function(event) {
                if (event === "dismissed") {
                    if (!done) callback(false);
                    done = true;
                    window.PopupNotifications.remove(self);
                }
            },
            persistWhileVisible: true
        });
}

prompt(window,
       "extensions.foo-addon.allowGeolocation",
       "Foo Add-on wants to know your location.",
       function callback(allowed) { alert(allowed); });

See also

  • {{ Interface("nsIGeolocationProvider") }}
  • {{ Interface("nsIDOMGeolocation") }}
  • {{ Interface("nsIDOMGeoPosition") }}
  • {{ Interface("nsIDOMGeoPositionCallback") }}
  • {{ Interface("nsIDOMGeoPositionError") }}
  • {{ Interface("nsIDOMGeoPositionErrorCallback") }}
  • {{ Interface("nsIDOMGeoPositionOptions") }}
  • {{ Interface("nsIDOMNavigatorGeolocation") }}
  • Geolocation API on w3.org
  • Demos about the Geolocation API
{{ HTML5ArticleTOC() }}

Fonte da revisão

<p><span id="result_box" lang="pt"><span class="hps">O Firefox 3.5</span> <span class="hps">e versões superiores o</span> <span class="hps">Geolocation</span> <span class="hps">API</span><span>, o qual permite</span> <span class="hps">que o usuário forneça</span> <span class="hps">sua localização para</span> <span class="hps">aplicações web</span><span>, se assim o</span> <span class="hps">desejar.</span> <span class="hps">Por razões de privacidade</span><span>, o usuário é</span> <span class="hps">solicitado a</span> <span class="hps">confirmar a permissão</span> <span class="hps">para relatar</span> <span class="hps">informações de localização.</span></span></p>
<p><span id="result_box" lang="pt"><span class="hps">O Firefox 3.5</span> <span class="hps">inclui suporte para</span> <span class="hps">localizá-lo</span> <span class="hps">com base</span> <span class="hps">nas informações da sua rede</span> <span class="hps">Wi-Fi</span> <span class="hps">usando</span> <span class="hps">o </span></span>Serviço Localização<span id="result_box" lang="pt"><span class="hps"> da Google (Google Location Services)</span><span>.</span> <span class="hps">Na comunicação</span> <span class="hps">entre o Firefox</span> <span class="hps">3.5 e</span> <span class="hps">Google,</span> <span class="hps">os dados são trocados</span> <span class="hps">incluindo dados</span> <span class="hps">de acesso</span> do <span class="hps">Acess Point WiFi</span> <span class="hps">, um</span> <span class="hps">código token de acesso</span> <span class="hps">(semelhante</span> <span class="hps">a um cookie de duas semanas</span><span class="hps">)</span><span> </span><span class="hps">e o endereço de</span> <span class="hps">IP</span> <span class="hps">do usuário.</span> <span class="hps">Para mais informações,</span> <span class="hps">por favor consulte a</span></span> <a class="external" href="http://www.mozilla.com/en-US/legal/privacy/" title="http://www.mozilla.com/en-US/legal/privacy/">Politica de Provacidade</a> da <span id="result_box" lang="pt"><span class="hps">Mozilla e</span></span> <a class="external" href="http://www.google.com/privacy-lsf.html" title="http://www.google.com/privacy-lsf.html">Politica de Privacidade</a> da Google <span id="result_box" lang="pt"><span class="hps">que cobrem como</span> <span class="hps">estes dados podem</span> <span class="hps">ser utilizados.</span> <span class="hps">Veja também o</span></span> <a class="external" href="http://mxr.mozilla.org/mozilla1.9.1/source/dom/src/geolocation/NetworkGeolocationProvider.js" title="http://mxr.mozilla.org/mozilla1.9.1/source/dom/src/geolocation/NetworkGeolocationProvider.js">codigo fonte</a> <span id="result_box" lang="pt"><span class="hps">se você está curioso</span> <span class="hps">como este serviço</span> <span class="hps">é implementado.</span></span></p>
<div class="note">
  <strong>Note:</strong> If your interest is in writing a geolocation provider -- a service which can be queried for the user's location -- please see {{ Interface("nsIGeolocationProvider") }}.&nbsp; You may also find the <a class="internal" href="/En/Monitoring_WiFi_access_points" title="En/Monitoring WiFi access points">WiFi access point monitoring service</a> interesting.</div>
<p>O Firefox 3.6 (Gecko 1.9.2) adicionou suporte usando o <a class="external" href="http://catb.org/gpsd/" title="http://catb.org/gpsd/">GPSD</a> (GPS&nbsp;daemon) serviço de Geolocalização do Linux.</p>
<div class="note">
  <strong>Note:</strong> Extensions hosted on addons.mozilla.org must explicitly <a href="#request-permission">request permission</a> before accessing geolocation data.</div>
<h2 id="The_geolocation_object">O objeto geolocation</h2>
<p>O aplicativo de geolocalização é utilizado através de um objeto filho chamado <code>geolocation </code>localizado dentro do objeto&nbsp;<code>navigator</code>.&nbsp; Se o objeto existe, os serviços de geolocalização estarão disponíveis. Você pode adicionalmente testar a presença da geolocalização:</p>
<pre class="brush: js">
if ("geolocation" in navigator) {
  /* geolocation is available */
} else {
&nbsp; alert("I'm sorry, but geolocation services are not supported by your browser.");
}
</pre>
<p>{{ gecko_minversion_header("1.9.2") }}</p>
<p>Ao iniciar no Gecko 1.9.2 (Firefox 3.6), add-ons podem obter o objeto de geolocalização obtendo a referência para o serviço de geolocaliazação como se ve a seguir:</p>
<pre class="brush: js">
var geolocation = Components.classes["@mozilla.org/geolocation;1"]
                            .getService(Components.interfaces.nsIDOMGeoGeolocation);
</pre>
<h3 id="Getting_the_current_position">Obtendo a posição atual</h3>
<p>Para obter a localização atual do usuário, você pode utiliza o método <code>getCurrentPosition().</code>&nbsp; Isto inicia uma requisição assíncrona para identificar a posição do usuário, e consulta ohardware de localizaçãopara conseguir informações atualizadas. Quando a posição é determinada, uma rotina específica de retorno é executada. Você pode opcionalmente gerar uma segunda rotina de retorno se um erro ocorrer.&nbsp; Um terceiro, e opcional, parâmetro é a interface "opções" onde você pode configurar o tempo máximo da posição recebida e o tempo a se esperar por uma solicitação.</p>
<p>Use <code>getCurrentPosition()</code> se você deseja uma única posição rapidamente, independente da precisão.&nbsp; Dispositivos com GPS, por exemplo, podem levar um minuto ou mais para conseguir a localização, e portanto dados menos precisos (localizxação do IP location ou rede wifi) podem retornar do método <code>getCurrentPosition()</code>.</p>
<pre class="brush: js">
navigator.geolocation.getCurrentPosition(function(position) {
&nbsp;&nbsp;do_something(position.coords.latitude, position.coords.longitude);
});</pre>
<p>O exemplo acima irá fazer a função the <code>do_something()</code> executar quando a localização for obtida.</p>
<h3 id="Watching_the_current_position">Verificando a posição atual</h3>
<p>If the position data changes (either by device movement or if more accurate geo information arrives) , you can set up a callback that is called with that updated position information.&nbsp; This is done using the <code>watchPosition()</code>&nbsp;function, which has the same input parameters as <code>getCurrentPosition()</code>.&nbsp; Its callback is called multiple times, allowing the browser to either update your location as you move, or provide a more accurate location as different techniques are used to geolocate you. &nbsp;The error callback, which is optional just as it is for <code>getCurrentPosition()</code>, is called only once, if there will never be valid results returned.</p>
<p>You can use <code>watchPosition()</code> without an initial <code>getCurrentPosition() </code>call.</p>
<pre class="brush: js">
var watchID&nbsp;= navigator.geolocation.watchPosition(function(position) {
&nbsp;&nbsp;do_something(position.coords.latitude, position.coords.longitude);
}
);</pre>
<p>The <code>watchPosition()</code> method returns an ID&nbsp;number that can be used to uniquely identify the requested position watcher; you use this value in tandem with the <code>clearWatch()</code>&nbsp;method to stop watching the user's location.</p>
<pre>
navigator.geolocation.clearWatch(watchID);
</pre>
<p><code>watchPosition() </code>accepts a success callback and error callback (like <code>getCurrentPosition</code>) and an optional <code>positionObjects</code> object, which can have three properties:</p>
<ul>
  <li><code>enableHighAccuracy</code> – A boolean which indicates to the device that you wish to obtain it’s most accurate readings (this parameter may or may not make a difference, depending on your hardware)</li>
  <li><code>maximumAge</code> – The maximum age (in milliseconds) of the reading (this is appropriate as the device may cache readings to save power and/or bandwidth)</li>
  <li><code>timeout</code> – The maximum time (in milliseconds) for which you are prepared to allow the device to try to obtain a Geo location</li>
</ul>
<p>A call to watchPosition could look like:</p>
<pre>
var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});</pre>
<p><a id="fck_paste_padding">A demo of watchPosition in use:&nbsp;</a><a class="external" href="http://www.thedotproduct.org/experiments/geo/">http://www.thedotproduct.org/experiments/geo/</a><br />
  <a id="fck_paste_padding"></a></p>
<h2 id="Describing_a_position">Describing a position</h2>
<p>The user's location is described using a Position object, which has the following fields:</p>
<dl>
  <dt>
    timestamp</dt>
  <dd>
    The time at which the reading was taken, as a <code>DOMTimeStamp</code>.</dd>
  <dt>
    coords</dt>
  <dd>
    An <a class="internal" href="/en/XPCOM_Interface_Reference/NsIDOMGeoPositionCoords" title="En/NsIDOMGeoPositionCoords"><code>nsIDOMGeoPositionCoords</code></a> object indicating the location.</dd>
  <dt>
    address {{ gecko_minversion_inline("1.9.2") }} {{obsolete_inline("14.0")}}</dt>
  <dd>
    An {{ interface("nsIDOMGeoPositionAddress") }} object specifying the corresponding address, if available.</dd>
</dl>
<h2 id="Handling_errors">Handling errors</h2>
<p>The error callback, if provided when calling <code>getCurrentPosition()</code>&nbsp;or <code>watchPosition()</code>, has the following signature:</p>
<pre>
function errorCallback(PositionError error);
</pre>
<p>The <code>PositionError</code> structure has the following fields:</p>
<dl>
  <dt>
    code</dt>
  <dd>
    A numeric error code which much be one of the following:</dd>
  <dt>
    <dfn id="unknown_error"><code>UNKNOWN_ERROR</code></dfn> (numeric value 0)</dt>
  <dd>
    The location acquisition process failed due to an error not covered by the definition of any other error code in this interface.</dd>
  <dt>
    <dfn id="permission_denied_error"><code>PERMISSION_DENIED</code></dfn> (numeric value 1)</dt>
  <dd>
    The location acquisition process failed because the application origin does not have permission to use the Geolocation API.</dd>
  <dt>
    <dfn id="position_unavailable_error"><code>POSITION_UNAVAILABLE</code></dfn> (numeric value 2)</dt>
  <dd>
    The position of the device could not be determined. One or more of the location providers used in the location acquisition process reported an internal error that caused the process to fail entirely.</dd>
  <dt>
    <dfn id="timeout_error"><code>TIMEOUT</code></dfn> (numeric value 3)</dt>
  <dd>
    The specified maximum length of time has elapsed before the implementation could successfully acquire a new Position object.</dd>
  <dd>
    &nbsp;</dd>
  <dt>
    message</dt>
  <dd>
    A human readable error message, suitable for use in logs and debugging -- but not for display to the user.</dd>
</dl>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <th>Browser</th>
      <th>Basic support</th>
      <th><a class="external" href="http://dev.w3.org/geo/api/spec-source-v2.html">Geolocation Level 2</a></th>
    </tr>
    <tr>
      <td>Internet Explorer</td>
      <td>IE9 RC</td>
      <td>---</td>
    </tr>
    <tr>
      <td>Firefox (Gecko)</td>
      <td><strong>3.5</strong> (1.9.1)</td>
      <td>---</td>
    </tr>
    <tr>
      <td>Opera</td>
      <td><strong>10.60</strong></td>
      <td>---</td>
    </tr>
    <tr>
      <td>Safari | Chrome | WebKit</td>
      <td>5 | 5 | 533</td>
      <td>---</td>
    </tr>
  </tbody>
</table>
<h2 id="Prompting_for_permission">Prompting for permission</h2>
<p>Any add-on hosted on addons.mozilla.org which makes use of geolocation data must explicitly request permission before doing so. The following function will request permission in a manner similar to the automatic prompt displayed for web pages. The user's response will be saved in the preference specified by the <code>pref</code> parameter, if applicable. The function provided in the <code>callback</code> parameter will be called with a boolean value indicating the user's response. If <code>true</code>, the add-on may access geolocation data.</p>
<pre class="brush: js">
function prompt(window, pref, message, callback) {
    let branch = Components.classes["@mozilla.org/preferences-service;1"]
                           .getService(Components.interfaces.nsIPrefBranch);

    if (branch.getPrefType(pref) === branch.PREF_STRING) {
        switch (branch.getCharPref(pref)) {
        case "always":
            return callback(true);
        case "never":
            return callback(false);
        }
    }

    let done = false;

    function remember(value, result) {
        return function() {
            done = true;
            branch.setCharPref(pref, value);
            callback(result);
        }
    }

    let self = window.PopupNotifications.show(
        window.gBrowser.selectedBrowser,
        "geolocation",
        message,
        "geo-notification-icon",
        {
            label: "Share Location",
            accessKey: "S",
            callback: function(notification) {
                done = true;
                callback(true);
            }
        }, [
            {
                label: "Always Share",
                accessKey: "A",
                callback: remember("always", true)
            },
            {
                label: "Never Share",
                accessKey: "N",
                callback: remember("never", false)
            }
        ], {
            eventCallback: function(event) {
                if (event === "dismissed") {
                    if (!done) callback(false);
                    done = true;
                    window.PopupNotifications.remove(self);
                }
            },
            persistWhileVisible: true
        });
}

prompt(window,
       "extensions.foo-addon.allowGeolocation",
       "Foo Add-on wants to know your location.",
       function callback(allowed) { alert(allowed); });
</pre>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{ Interface("nsIGeolocationProvider") }}</li>
  <li>{{ Interface("nsIDOMGeolocation") }}</li>
  <li>{{ Interface("nsIDOMGeoPosition") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionCallback") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionError") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionErrorCallback") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionOptions") }}</li>
  <li>{{ Interface("nsIDOMNavigatorGeolocation") }}</li>
  <li><a class="external" href="http://dev.w3.org/geo/api/spec-source.html" title="http://dev.w3.org/geo/api/spec-source.html">Geolocation API on w3.org</a></li>
  <li><a href="/en-US/demos/tag/tech:geolocation" title="en-US/demos/tag/tech:geolocation/">Demos about the Geolocation API</a></li>
</ul>
<div>
  {{ HTML5ArticleTOC() }}</div>
<!-- languages({
  "es": "es/Usar_la_Geolocalización"
}) -->
Reverter para esta revisão