react-geocode
TypeScript icon, indicating that this package has built-in type declarations

1.0.0-alpha.1 • Public • Published

react-geocode

Despite its name, this project

 _    ,          _ __                                                           _ __
' )  /          ' )  )   _/_ /                _/_        /             _/_ /   ' )  )           _/_
 /--/ __.  _     /  / __ /  /_  o ____  _,    /  __   __/ __   , , , o /  /_    /--' _  __.  _. /
/  (_(_/|_/_)_  /  (_(_)<__/ /_<_/ / <_(_)_  <__(_)  (_/_(_)  (_(_/_<_<__/ /_  /  \_</_(_/|_(__<__
                                        /|
                                       |/

A module to transform a description of a location (i.e. street address, town name, etc.) into geographic coordinates (i.e. latitude and longitude) and vice versa.

This module uses Google Maps Geocoding API and requires an API key for purposes of quota management. Please check this link out to obtain your API key.

Install

yarn add react-geocode

or

npm install --save react-geocode

Example

import {
  setKey,
  setDefaults,
  setLanguage,
  setRegion,
  fromAddress,
  fromLatLng,
  fromPlaceId,
  setLocationType,
  geocode,
  RequestType,
} from "react-geocode";

// Set default response language and region (optional).
// This sets default values for language and region for geocoding requests.
setDefaults({
  key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // Your API key here.
  language: "en", // Default language for responses.
  region: "es", // Default region for responses.
});

// Alternatively

// Set Google Maps Geocoding API key for quota management (optional but recommended).
// Use this if you want to set the API key independently.
setKey("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"); // Your API key here.

// Set default response language (optional).
// This sets the default language for geocoding responses.
setLanguage("en"); // Default language for responses.

// Set default response region (optional).
// This sets the default region for geocoding responses.
setRegion("es"); // Default region for responses.

// Get latitude & longitude from address.
fromAddress("Eiffel Tower")
  .then(({ results }) => {
    const { lat, lng } = results[0].geometry.location;
    console.log(lat, lng);
  })
  .catch(console.error);

// Get address from latitude & longitude.
fromLatLng(48.8583701, 2.2922926)
  .then(({ results }) => {
    const { lat, lng } = results[0].geometry.location;
    console.log(lat, lng);
  })
  .catch(console.error);

// Get latitude & longitude from place_id.
fromPlaceId("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
  .then(({ results }) => {
    const { lat, lng } = results[0].geometry.location;
    console.log(lat, lng);
  })
  .catch(console.error);

// Alternatively, use geocode function for consistency
geocode(RequestType.ADDRESS, "Eiffel Tower")
  .then(({ results }) => {
    const { lat, lng } = results[0].geometry.location;
    console.log(lat, lng);
  })
  .catch(console.error);

// Set default location_type filter (optional).
// This sets the default location type filter to "ROOFTOP" for geocoding responses.
setLocationType("ROOFTOP");

// Get address from latitude & longitude.
geocode(RequestType.LATLNG, "48.8583701,2.2922926")
  .then(({ results }) => {
    const address = results[0].formatted_address;
    console.log(address);
  })
  .catch(console.error);

// Get formatted address, city, state, country from latitude & longitude.
geocode(RequestType.LATLNG, "48.8583701,2.2922926", {
  location_type: "ROOFTOP", // Override location type filter for this request.
  enable_address_descriptor: true, // Include address descriptor in response.
})
  .then(({ results }) => {
    const address = results[0].formatted_address;
    const { city, state, country } = results[0].address_components.reduce(
      (acc, component) => {
        if (component.types.includes("locality"))
          acc.city = component.long_name;
        else if (component.types.includes("administrative_area_level_1"))
          acc.state = component.long_name;
        else if (component.types.includes("country"))
          acc.country = component.long_name;
        return acc;
      },
      {}
    );
    console.log(city, state, country);
    console.log(address);
  })
  .catch(console.error);

// Override default options for geocode requests.
// These examples demonstrate how to override default settings for specific requests.
const addressResponse = await geocode(RequestType.ADDRESS, "Eiffel Tower", {
  language: "en",
  region: "sp",
});

const placeIdResponse = await geocode(
  RequestType.PLACE_ID,
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  { language: "en", region: "sp" }
);

const latlngResponse = await geocode(
  RequestType.LATLNG,
  "48.8583701,2.2922926",
  { language: "en", region: "sp", enable_address_descriptor: true }
);

API

Methods

Method Params Return Type Description
setKey key - function Your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key.
setLanguage language - function Specify the language of the parsed address. List of available language codes.
setComponents components - function A components filter with elements separated by a pipe ( | ). See more information about component filtering.
setRegion region - function Specify the region of the parsed address. For more information, see Region Biasing.
setBounds bounds - function The bounding box of the viewport within which to bias geocode results more prominently. For more information, see Viewport Biasing.
setLocationType location_type - function A filter of one or more location types, separated by a pipe ( | ). The following values are supported: ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, and APPROXIMATE.
setResultType result_type - function A filter of one or more address types, separated by a pipe ( | ).
setOutputFormat outputFormat (OutputFormat) - function Sets the desired output format for geocoding requests. The format can be either XML or JSON.
enableAddressDescriptor enableAddressDescriptor (boolean) - function Sets whether to include an address descriptor in the reverse geocoding response.
geocode requestType (RequestType | string), value (string), options? (GeocodeOptions) response function Get latitude & longitude from an address. Optional params.
fromLatLng latitude, longitude, *apiKey, *language, *region response function Get address from latitude & longitude. Optional params.
fromAddress address, *apiKey, *language, *region response function Get latitude & longitude from address. Optional params.
fromPlaceId placeId, *apiKey, *language, *region response function Get latitude & longitude from place id. Optional params.

Geocode(requestType, value, *options)

Sends a geocoding request to the Google Geocoding API for a given address. To geocode an address, use the geocode function:

import { geocode, RequestType } from "react-geocode";
const address = "1600 Amphitheatre Parkway, Mountain View, CA";
geocode(RequestType.ADDRESS, address)
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.error(error);
  });
Parameters
  • requestType (RequestType | string): Identifier to specify the type of request (place_id, address, latlng, components etc).
  • value (string): The value to geocode. This can be an address, latitude and longitude (lat,lng), or a place ID.
  • options (optional object): Additional options for the geocoding request.
    • key (string): API key for Google Geocoding API.
    • language (string): Language code for the response.
    • region (string): Region code for the response.
    • components (string): Component filtering for the response.
    • bounds (string): Bounding box for the response.
    • result_type (string): Result type filtering for the response.
    • location_type (string): Location type filtering for the response.

You can also pass additional options to the geocode function:

geocode("latlng", "48.8583701,2.2922926", {
  key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  language: "en",
  region: "us",
})
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.error(error);
  });
Returns

The geocode function returns a Promise that resolves with the geocoding response object, or rejects with an error if the request fails.

A Promise that resolves with a GeocodeResponse object, which has the following properties:

  • status (string): The status of the geocoding request. Possible values are "OK", "ZERO_RESULTS", "OVER_QUERY_LIMIT", "REQUEST_DENIED", "INVALID_REQUEST", and "UNKNOWN_ERROR".
  • results (array): An array of geocoding results. Each result is an object with the following properties:
    • formatted_address (string): The human-readable address of the location.
    • geometry (object): The geometry of the location, including its latitude, longitude, and location type.
    • address_components (array): An array of address components for the location, including its street number, street name, city, state, postal code, and country.

License

This project is licensed under the MIT License.

Note:

Make sure to replace "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" with your actual API key from the Google Cloud Console. Also, feel free to modify the examples and add any necessary configurations based on your specific requirements.

Let me know if you need any further assistance!

Follow me on Twitter: @shukerullah

Buy Me A Coffee

Package Sidebar

Install

npm i react-geocode

Weekly Downloads

90,873

Version

1.0.0-alpha.1

License

MIT

Unpacked Size

21.4 kB

Total Files

5

Last publish

Collaborators

  • shukerullah