Use-geo-location NPM

Custom react hook for getting user's geo location. Google Maps Geocoding API can also be used by providing a valid API key to the hook. Supports TypeScript by default.

Installation

$ yarn add use-geo-location

$ npm i use-geo-location

Basic Usage

Refer to this link for Google Maps response.

import React from 'react';
import { useGeoLocation } from 'use-geo-location';

const TestComponent = () => {
  const apiKey = 'YOUR_GOOGLE_MAPS_API_KEY';
  const { latitude, longitude, loading, error, timestamp, googleMapsResults } = useGeoLocation({ apiKey }); // apiKey is optional

  return (
    <>
      {loading ? (
        <span>Loading...</span>
      ) : (
        <div>
          <span>latitude: {latitude}</span>
          <br />
          <span>longitude: {longitude}</span>
        </div>
      )}
    </>
  );
};

Function description

`useGeoLocation()`

The following can be provided as options:

Param	Optional	Type
apiKey	Yes	string
watch	Yes	boolean
config	Yes	`{ enableHighAccuracy: boolean; timeout: number; maximumAge: number; }`

// e.g.
const config = {
  enableHighAccuracy: false, // default value is false
  timeout: 10000, // default value is 10000
  maximumAge: 0, // default value is 0
}
const apiKey = 'YOUR_GOOGLE_MAPS_API_KEY'
useGeoLocation({ watch: true, config, apiKey }) // watch is set to `false` by default

Options

Setting enableHighAccuracy: true may result in slower response and increased power consumption.
timeout is the length of time allowed in milliseconds until it gets the user's coords back
maximumAge is the length of time in milleseconds until it retries to get user's location. Setting this value to 0 means it will immediately attempt to acquire user's location.

useGeoLocation() will return the following:

Value	Type	Description
latitude	`number \\| undefined`	user's latitude
longitude	`number \\| undefined`	user's longitude
loading	`boolean`	loading status
error	`Error`	any error caught from fetching location
timestamp	`number \\| undefined`	unix timestamp of whem user location was last fetched
googleMapsResults	`GoogleMapsResults \\| undefined`	google maps api response for user's latitude and longitude

GoogleMapsResults

Value	Type
plus_code	`any`
status	`string`
results	`any[]`

Please refer to this link for details on what Google Maps API returns.

Watch parameter

If watch is set to true (set to true by default), it'll continuously continuously attempt to get user's position, this is useful when user is using a mobile device. If it's set to true, it will fetch user's position on render and cache it. The cached value will be used until it reaches its maximumAge, set in options.

Error handling

There are two main types of error useGeoLocation() can return.

GeolocationPositonError

Please see https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError for details.

When geo location is not available on user's device, it will return the following error.

{
  code: -1,
  message: 'Geolocation not available',
  PERMISSION_DENIED: 1,
  POSITION_UNAVAILABLE: 2,
  TIMEOUT: 3,
}

Google Maps API Error

Refer to this link for details on Google Maps API errors. Here's a short summary of status message.

Status	Description
`OK`	indicates that no errors occurred; the address was successfully parsed and at least one geocode was returned.
`ZERO_RESULTS`	indicates that the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.
`OVER_DAILY_LIMIT`	indicates any of the following:The API key is missing or invalid.Billing has not been enabled on your account.A self-imposed usage cap has been exceeded.The provided method of payment is no longer valid (for example, a credit card has expired).
`OVER_QUERY_LIMIT`	indicates that you are over your quota.
`REQUEST_DENIED`	indicates that your request was denied.
`INVALID_REQUEST`	generally indicates that the query (address, components or latlng) is missing.
`UNKNOWN_ERROR`	indicates that the request could not be processed due to a server error. The request may succeed if you try again.