mapnests-react-native-sdk

Readme Top

Mapnests React Native TypeScript SDK

Map Nests - React Native Compatible

A secure and efficient TS SDK for the **Mapnests Platform**, enabling powerful geospatial capabilities such as **Search (Geocoding)**, **Reverse (Reverse Geocoding)**, and **Distance Matrix**.

📚 Table of Contents

• Installation

• Quick Start

• Core Features

  • Distance Matrix
  • Pairwise Route Summary
  • Multi Source Route Summary
  • Distance Matrix Details
  • Search
  • Reverse
  • Autocomplete
  • Multi Stop Point
  • Detailed Geolocation Information
  • Geocode Search
  • Search By Radius
  • Detailed Search By PlaceId

• License

• Contact

(back to top)

Installation

npm install mapnests-react-native-sdk

Import into your React Native project:

import { Client, Mode } from "mapnests-react-native-sdk";

Requirements

• React Native >= 0.60.0
• Node.js >= 22.0.0

(back to top)

Quick Start

import { Client, Mode } from "mapnests-react-native-sdk";

(async function () {
  const client = new Client("YOUR_API_KEY", "your.package.name");

   // With optional timeout (in milliseconds)
  const clientWithTimeout = new Client("YOUR_API_KEY", "your.package.name", 30000); // 30 seconds
  
  const result = await client.search({ Query: "Dhaka" });
  console.log("Search result:", result);
})();

(back to top)

Core Features

Distance Matrix

Calculates the distance and estimated time of arrival (ETA) between origin and destination points.

Example Input:

const res = await client.distanceMatrix({
    OriginLat: 23.8103,
    OriginLon: 90.4125,
    DestLat: 23.75,
    DestLon: 90.42,
    Mode: Mode.Walking,
});
console.log(res);

Example Output:

{
    "data": {
        "distanceInMetres": 8900,
        "etaInSeconds": 1300
    }
}

(back to top)

Pairwise Route Summary

Computes distances, ETAs and geometries for multiple source-destination pairs in a single request. This is ideal for optimizing batch operations and comparing route statistics efficiently.

Example Input:

const summary = await client.pairwiseRouteSummary({
    pairs: [
        {
            id: 1,
            src: { lat: 23.8103, lon: 90.4125 },
            dest: { lat: 23.75, lon: 90.42 },
            mode: Mode.Walking,
        },
        {
            id: 2,
            src: { lat: 23.7806, lon: 90.3984 },
            dest: { lat: 23.774, lon: 90.3681 },
            mode: Mode.Car,
        },
    ],
});
console.log(summary);

Example Output:

{
    "status": true,
    "message": "success",
    "data": [
        {
            "id": 1,
            "distanceInMeters": 8900,
            "etaInSeconds": 1300,
            "geometry": "encoded_polyline_string"
        },
        {
            "id": 2,
            "distanceInMeters": 4800,
            "etaInSeconds": 700,
            "geometry": "another_encoded_polyline"
        }
    ]
}

(back to top)

Multi Source Route Summary

Computes distances, ETAs and geometries for multiple source-destination pairs in a single request. This is ideal for optimizing batch operations and comparing route statistics efficiently.

Example Input:

const summary = await client.multiSourceRouteSummary({
    sources: [
        {
            id: 1,
            lat: 23.7805733,
            lon: 90.2792399,
            mode: "car",
        },
        {
            id: 2,
            lat: 23.75,
            lon: 90.36,
            mode: "car",
        },
        {
            id: 3,
            lat: 23.7,
            lon: 90.42,
            mode: "car",
        },
        {
            id: 4,
            lat: 23.7654321,
            lon: 90.3456789,
            mode: "car",
        },
        {
            id: 5,
            lat: 23.7123456,
            lon: 90.3765432,
            mode: "car",
        },
    ],
    destination: {
        lat: 23.810332,
        lon: 90.412518,
    },
});

Example Output:

{
    "data": {
        "routeSummaries": [
            {
                "id": 1,
                "distanceInMeters": 23782.9,
                "etaInSeconds": 1720,
                "geometry": "encoded_polyline_string"
            },
            {
                "id": 2,
                "distanceInMeters": 13421.9,
                "etaInSeconds": 1084.9,
                "geometry": "encoded_polyline_string"
            },
            {
                "id": 3,
                "distanceInMeters": 15212.3,
                "etaInSeconds": 1285.3,
                "geometry": "encoded_polyline_string"
            },
            {
                "id": 4,
                "distanceInMeters": 14120.2,
                "etaInSeconds": 1129.3,
                "geometry": "encoded_polyline_string"
            },
            {
                "id": 5,
                "distanceInMeters": 16555.4,
                "etaInSeconds": 1388,
                "geometry": "encoded_polyline_string"
            }
        ]
    },
    "message": "Success",
    "status": true
}

(back to top)

Distance Matrix Details

Returns step-by-step routing metadata, including geometry, waypoints, and navigation instructions.

Example Input:

const details = await client.distanceMatrixDetails({
    OriginLat: 23.7806,
    OriginLon: 90.3984,
    DestLat: 23.774,
    DestLon: 90.3681,
    Mode: Mode.Car,
});
console.log(details);

Example Output (simplified):

{
  "status": true,
  "message": "success",
  "data": {
    "routeResponse": {
      "routes": [
        {
          "distance": 4800,
          "duration": 700,
          "geometry": "encoded_polyline",
          "legs": [ ... ]
        }
      ]
    }
  }
}

📘 For detailed documentation on all response fields (e.g., routes, legs, steps, maneuver, etc.), check the Distance Matrix Response Reference.

(back to top)

Search

Finds places, streets, and landmarks using text-based queries. The search can also be refined by providing latitude and longitude with radius support.

Example Input:

const searchRes = await client.search({
    Query: "Mirpur",
});
console.log(searchRes);

To get only Zone Data provide ActiveLocations

const searchRes = await client.search({
    Query: "Bashundhara Residential Area, Dhaka",
    ActiveLocations: true
});
console.log(searchRes);

Example Output:

{
  "data": {
    "items": [
      {
        "placeId": "61aa7fe80c299c0a67966c8f2fbc9093626e38093c62cea2dc07b561f30f9d8c",
        "lat": 23.8074008,
        "lon": 90.3682003,
        "types": [ "amenity", "bus_station", "amenity" ],
        "address": "Bangladesh",
        "name": "Mirpur-10",
        "houseNumber": "",
        "houseName": "",
        "street": "",
        "phone": "",
        "website": "",
        "country": "Bangladesh",
        "city": "",
        "thana": "",
        "division": "",
        "district": "",
        "postalCode": "1216",
        "plusCode": "",
        "sublocality": "",
        "localArea": ""
      }
    ],
    "itemsPerPage": 1,
    "pageNumber": 1,
    "totalItems": 27,
    "totalPages": 27
  },
  "message": "Success",
  "status": true
}

(back to top)

Reverse

Reverse geocodes coordinates to return detailed location information for a given latitude and longitude.

Example Input:

const revRes = await client.reverse({ Lat: 23.795295, Lon: 90.416803});
console.log(revRes);

Example Output:

{
  "data": {
    "placeId": "a4d8c105e24fbc3d91bb0486e1701fa20b9b56329df0fc5c47f7df003e3cc579",
    "category": "",
    "type": "yes",
    "class": "building",
    "name": "Concord Ik Tower",
    "address": "Concord Ik Tower, House#2, Road 94, Gulshan North Avenue, Gulshan 2, Gulshan, Dhaka-1212",
    "country": "Bangladesh",
    "city": "Gulshan 2, Dhaka",
    "thana": "Gulshan",
    "district": "Dhaka",
    "division": "",
    "postalCode": "1212",
    "website": "",
    "houseNumber": "2",
    "houseName": "",
    "subLocality": "",
    "localArea": "",
    "types": [
      "building",
      "yes",
      "building"
    ]
  },
  "message": "Success",
  "status": true
}

(back to top)

Autocomplete

Auto Complete suggests relevant places, streets, and landmarks as you type a partial search query.

Example Input:

//Without optional value
const autoCompleteRes = await client.autocomplete({ Query: "Gulshan Road"});
console.log(autoCompleteRes);

// Optional parameter: ActiveZone.
// If ActiveZone is set to true, the search results will be returned within the zone. (By Default ActiveZone is true)
// If ActiveZone is set to false, the search results will be not consider any zone data.
const autoCompleteRes = await client.autocomplete({ Query: "Gulshan Road", ActiveZone: true });
console.log(autoCompleteRes);

// Optional parameters: Latitude, Longitude, and Radius.
// If provided, the search results will be returned within a specified radius,
// using the given latitude and longitude as the center point.
const autoCompleteRes = await client.autocomplete({ Query: "Gulshan Road", Lat: 23.7806, Lon: 90.3984, Radius: 5000 });
console.log(autoCompleteRes);

// Optional parameter: Limit.
// If provided, the search results will be returned within a specified limit.
const autoCompleteRes = await client.autocomplete({ Query: "Gulshan Road", Limit: 1 });
console.log(autoCompleteRes);

Example Output:

{
  "data": [
    {
      "placeId": "4e7820118661ce107f308dff7648bf0a9d2847b78b720b08c9d39fe3662c4a8c",
      "name": "Gulshan",
      "address": "Gulshan, House#76, Palolika, Road-24, Gulshan-1, Gulshan, Dhaka-1212",
      "types": [
        "landuse",
        "residential",
        "landuse"
      ]
    }
  ],
  "message": "Success",
  "status": true
}

AutocompleteV2

Auto Complete suggests relevant places, streets, and landmarks as you type a partial search query.

Example Input:

const autoCompleteResV2 = await client.autocompleteV2({ Query: "Mirpur", ZoneActiveOnly: true });
console.log(autoCompleteResV2);

Example Output:

{
  "data": [
    {
      "placeId": "89cd0fb23cb145b05778f680aed03d62399fd5627b7e96799967983e2c52276e",
      "name": "GoynaBakhso Mirpur",
      "address": "GoynaBakhso Mirpur, House#03, Mirpur New Market, Majar Road, Mirpur-01, Mirpur, Dhaka-1216",
      "types": [
        "shop",
        "clothes",
        "shop"
      ]
    }
  ],
  "message": "Success",
  "status": true
}

(back to top)

Autocomplete Without Zone

Auto Complete suggests relevant places, streets, and landmarks as you type a partial search query.

Example Input:

const autocompleteResWithoutZone = await client.autocompleteWithoutZone({ Query: "Uttara"});
console.log( JSON.stringify(autocompleteResWithoutZone,));

Example Output:

{
  "data": [
    {
      "placeId": "7d7e8fd275bfd9be9853ada14417d104e824d1c11600599bd326fb858429d83c",
      "name": "Uttara",
      "address": "Uttara, House#21, Road 17, Sector 11, Uttara, Dhaka-1230",
      "types": [
        "amenity",
        "restaurant",
        "amenity"
      ]
    }
    ]
}

Search By Radius

Finds places, streets, and landmarks using text-based queries. All searches are restricted to results within the specified radius, which requires latitude, longitude, and radius parameters.

Example Input:

const searchByRadiusRes = await cl.searchByRadius({ 
        Query: "uttara", Lat: 23.7272064, Lon: 90.3861125, Radius: 5000
    });
console.log(searchByRadiusRes);

Example Output:

{
  "data": {
    "items": [
      {
        "placeId": "f6e5bf556e2163d89f65d634b6456d28736a6a72dc1c1df933a8b13d0597956a",
        "lat": 23.714221,
        "lon": 90.4059638,
        "types": [ "amenity", "bank", "amenity" ],
        "address": "Uttara Bank",
        "name": "Uttara Bank",
        "houseNumber": "",
        "houseName": "",
        "street": "Nawab Yousuf Sarak",
        "phone": "",
        "website": "",
        "country": "Bangladesh",
        "city": "",
        "thana": "",
        "division": "",
        "district": "",
        "postalCode": "1100",
        "plusCode": "",
        "sublocality": "",
        "localArea": ""
      }
    ],
    "itemsPerPage": 1,
    "pageNumber": 1,
    "totalItems": 12,
    "totalPages": 12
  },
  "message": "Success",
  "status": true
}

(back to top)

Multi Stop Point

Calculates distance, ETA, and route geometry for a journey starting from a single source and passing through multiple stop points in sequence. It returns both total and per-segment results, processes routes concurrently for efficiency, and supports multiple stops.

Example Input:

  const multiStopRes = await client.multiStopPoint({
            Src: { lat: 23.8103, lon: 90.4125 },
            StopPoints: [
                { id: 1, lat: 23.8113, lon: 90.4135 },
                { id: 2, lat: 23.8123, lon: 90.4145 },
                { id: 3, lat: 23.8133, lon: 90.4155 },
            ],
            Mode: Mode.Car,
        });

Example Output:

 {
  "data": {
    "distanceInMeters": 1357.7999725341797,
    "etaInSeconds": 252.10000228881836,
    "routeSummaries": [
      {
        "id": 1,
        "source": {
          "lat": 23.8103,
          "lon": 90.4125
        },
        "stopPoint": {
          "lat": 23.8113,
          "lon": 90.4135
        },
        "distanceInMeters": 213.3,
        "etaInSeconds": 47.3,
        "geometry": "_nipCcuyfPCkB}DJCgB"
      },
      {
        "id": 2,
        "source": {
          "lat": 23.8113,
          "lon": 90.4135
        },
        "stopPoint": {
          "lat": 23.8123,
          "lon": 90.4145
        },
        "distanceInMeters": 191.4,
        "etaInSeconds": 44.5,
        "geometry": "etipCk{yfPEaDQc@}CD"
      },
      {
        "id": 3,
        "source": {
          "lat": 23.8123,
          "lon": 90.4145
        },
        "stopPoint": {
          "lat": 23.8133,
          "lon": 90.4155
        },
        "distanceInMeters": 953.1,
        "etaInSeconds": 160.3,
        "geometry": "{yipCkazfPmBDG}CqO`@UKYo@CWT_E`FS@p@jAPpDMBbC"
      }
    ]
  },
  "message": "Success",
  "status": true
}

(back to top)

Geocode Search

Search for details about places, streets, and landmarks using a text query.

Example Input:

const geocodeRes = await client.geocode({ Query: "Mirpur" });

Example Output:

{
  "data": [
    {
      "place_id": 373373,
      "lat": "23.9363038",
      "lon": "88.997764",
      "category": "boundary",
      "type": "administrative",
      "place_rank": 12,
      "importance": 0.24000999999999997,
      "addresstype": "town",
      "name": "Mirpur",
      "display_name": "Mirpur, Kushtia District, Khulna Division, Bangladesh",
      "address": ""
    },
    {
      "place_id": 399534,
      "lat": "23.1460109",
      "lon": "90.7556272",
      "category": "place",
      "type": "village",
      "place_rank": 19,
      "importance": 0.14667666666666662,
      "addresstype": "village",
      "name": "Mirpur",
      "display_name": "Mirpur, Faridganj Upazila, Chandpur District, Chattogram Division, Bangladesh",
      "address": ""
    },
    {
      "place_id": 479355,
      "lat": "23.817758949999998",
      "lon": "90.37244789599441",
      "category": "place",
      "type": "suburb",
      "place_rank": 19,
      "importance": 0.14667666666666662,
      "addresstype": "suburb",
      "name": "Mirpur",
      "display_name": "Mirpur, Dhaka, Dhaka Metropolitan, Dhaka District, Dhaka Division, 1216, Bangladesh",
      "address": ""
    }
  ],
  "message": "Success",
  "status": true
}

(back to top)

Detailed Search By PlaceId

Provide detailed geolocation information for a place using its unique place_id, including address, coordinates, administrative regions, contact details, and metadata.

Example Input:

const detailsByPlaceId = await client.details({ 
      PlaceId: "4355aad6b8eb0b4f0ee3fa972ff9ac3fdc2d7f86f634d81f79dcf396f21826a0" 
    });
console.log(detailsByPlaceId);

Example Output:

{
  "data": {
    "placeId": "4355aad6b8eb0b4f0ee3fa972ff9ac3fdc2d7f86f634d81f79dcf396f21826a0",
    "lat": 23.8060476,
    "lon": 90.3744551,
    "types": [
      "office",
      "office"
    ],
    "address": "Notari Public, House# 42, Mirpur Road, Senpara Parbata, Mirpur, Dhaka-1216",
    "name": "Mirpur",
    "houseNumber": "42",
    "houseName": "",
    "street": "Mirpur Road",
    "phone": "",
    "website": "",
    "country": "Bangladesh",
    "city": "Mirpur, Dhaka",
    "thana": "Kafrul",
    "division": "",
    "district": "Dhaka",
    "postalCode": "1216",
    "plusCode": "",
    "sublocality": "",
    "localArea": ""
  },
  "message": "Success",
  "status": true
}

(back to top)

License

This project is licensed under the MIT License.

(back to top)

Contact

📧 [e-mail] Explain