Add JS examples for Geocoding and Reverse Geocoding

Author: Alfiya Tarasenko

.gitignore

@@ -1,2 +1,5 @@
 .vscode/settings.json
-.DS_Store
+.DS_Store
+**/**/node_modules
+**/**/package-lock.json
+**/**/results.json

README.md

@@ -146,7 +146,7 @@ This example demonstrates how to fetch **places data** from the Geoapify Places
 - [Asyncio](https://docs.python.org/3/library/asyncio.html), [Aiohttp](https://docs.aiohttp.org/)
 
 
-### **8. Python: [Route Planner Result Processor](https://github.com/geoapify/maps-api-code-samples/tree/main/python/route-planner)**
+### **10. Python: [Route Planner Result Processor](https://github.com/geoapify/maps-api-code-samples/tree/main/python/route-planner)**
 
 #### **Description:**  
 This example demonstrates how to process a request to the **Geoapify Route Planner API**, generate structured outputs for each agent, and visualize their assigned routes.
@@ -164,6 +164,42 @@ This example demonstrates how to process a request to the **Geoapify Route Plann
 - [Geoapify Routing API](https://www.geoapify.com/routing-api/)
 - [Folium Library](https://python-visualization.github.io/folium/)
 
+
+### **11. JavaScript(Node.js): [Batch Geocoding with Rate Limiting](https://github.com/geoapify/maps-api-code-samples/tree/main/javascript/geocoding-with-RPS-limit-respect)**
+
+#### **Description:**  
+This example demonstrates how to geocode a large number of addresses using the **Geoapify Geocoding API**, while automatically respecting API rate limits with the help of the [`@geoapify/request-rate-limiter`](https://www.npmjs.com/package/@geoapify/request-rate-limiter) package.
+
+#### **Features:**
+- Reads addresses from a plain text file (`input.txt`), one per line.
+- Sends geocoding requests with a limit of **5 requests per second** (default for Free plan).
+- Outputs results to:
+  - `results.json` — full API response per address.
+- Logs geocoding progress and errors in real-time.
+- Built with **ES modules**, `node-fetch`, and Geoapify’s official rate limiter.
+
+#### **APIs Used:**
+- [Geoapify Geocoding API](https://www.geoapify.com/geocoding-api/)
+- [@geoapify/request-rate-limiter](https://www.npmjs.com/package/@geoapify/request-rate-limiter)
+
+### **12. JavaScript(Node.js): [Batch Reverse Geocoding](https://github.com/geoapify/maps-api-code-samples/tree/main/javascript/reverse-geocoding-lat-lon-to-address)**
+
+#### **Description:**  
+This example demonstrates how to perform batch **reverse geocoding** using the **Geoapify Reverse Geocoding API**. It reads a list of latitude/longitude pairs from a text file, resolves them into addresses, and saves the output as structured JSON — all while respecting rate limits.
+
+#### **Features:**
+- Reads coordinate pairs (`lat,lon`) from `input.txt`.
+- Calls the **Geoapify Reverse Geocoding API** for each location.
+- Uses [`@geoapify/request-rate-limiter`](https://www.npmjs.com/package/@geoapify/request-rate-limiter) to automatically respect the 5 RPS API limit.
+- Logs progress and handles errors gracefully.
+- Saves results to a `results.json` file in structured format.
+
+#### **APIs Used:**
+- [Geoapify Reverse Geocoding API](https://www.geoapify.com/reverse-geocoding-api/)
+- [@geoapify/request-rate-limiter](https://www.npmjs.com/package/@geoapify/request-rate-limiter)
+- [node-fetch](https://www.npmjs.com/package/node-fetch)
+
+
 ## Upcoming Code Samples
 
 We plan to expand this repository with code samples in various programming languages, demonstrating different Geoapify APIs, including:

javascript/geocoding-with-RPS-limit-respect/README.md

@@ -0,0 +1,147 @@
+# Geoapify Batch Geocoding Script
+
+This Node.js script performs batch geocoding using the [Geoapify Geocoding API](https://www.geoapify.com/geocoding-api/) while **respecting rate limits** through the official [`@geoapify/request-rate-limiter`](https://www.npmjs.com/package/@geoapify/request-rate-limiter) package. It reads addresses from a text file, geocodes them, and writes the results to a JSON file.
+
+## Highlights
+
+- Uses [@geoapify/request-rate-limiter](https://www.npmjs.com/package/@geoapify/request-rate-limiter) to automatically respect Geoapify RPS limits
+- Reads addresses from `input.txt`
+- Outputs full results to `results.json`
+- Logs geocoding progress and errors
+- Built with ES Modules and `node-fetch`
+
+## Requirements
+
+- Node.js **v16+**
+- A [Geoapify API key](https://myprojects.geoapify.com)
+- The following dependencies:
+  - [`@geoapify/request-rate-limiter`](https://www.npmjs.com/package/@geoapify/request-rate-limiter)
+  - [`node-fetch`](https://www.npmjs.com/package/node-fetch)
+
+## Install dependencies
+
+All required dependencies are already listed in the `package.json` file.  
+To install them, simply run:
+
+```bash
+npm install
+```
+
+## Usage
+
+1. **Create `input.txt`**  
+   List one address per line:
+
+   ```
+   1600 Amphitheatre Parkway, Mountain View, CA
+   1 Infinite Loop, Cupertino, CA
+   ```
+
+2. Use your API key
+
+Replace 'YOUR_API_KEY' with you Geoapify API key.
+
+3. **Run the script**
+
+   ```bash
+   node geocode.js
+   ```
+
+4. **View output**
+
+   - `results.json`: contains structured geocoding results
+
+## Code Overview
+
+### Powered by [`@geoapify/request-rate-limiter`](https://www.npmjs.com/package/@geoapify/request-rate-limiter)
+
+This script relies on Geoapify's official rate limiter to stay within the Free plan's 5 requests per second. The package makes it easy to batch and throttle API calls without hitting limits.
+
+### Key Components
+
+- `readAddressesFromFile()` – Loads addresses from `input.txt`.
+- `createGeocodingRequest()` – Creates individual throttled fetch requests.
+- `geocodeBatch()` – Processes all addresses using `rateLimitedRequests()` with:
+  - `limit: 5 RPS`
+  - `batchSize: 10`
+  - progress and batch logging
+- `saveToJSONFile()` – Writes structured results to disk.
+
+## Output Example
+
+A successful geocode result:
+
+```json
+{
+  "address": "North Oak Street, Bethalto, IL 62010, USA,",
+  "result": {
+    "datasource": {
+      "sourcename": "openstreetmap",
+      "attribution": "© OpenStreetMap contributors",
+      "license": "Open Database License",
+      "url": "https://www.openstreetmap.org/copyright"
+    },
+    "name": "North Oak Street",
+    "country": "United States",
+    "country_code": "us",
+    "state": "Illinois",
+    "county": "Madison County",
+    "city": "Bethalto",
+    "postcode": "62010",
+    "street": "North Oak Street",
+    "iso3166_2": "US-IL",
+    "lon": -90.0421214,
+    "lat": 38.9103244,
+    "state_code": "IL",
+    "result_type": "street",
+    "formatted": "North Oak Street, Bethalto, IL 62010, United States of America",
+    "address_line1": "North Oak Street",
+    "address_line2": "Bethalto, IL 62010, United States of America",
+    "timezone": {
+      "name": "America/Chicago",
+      "offset_STD": "-06:00",
+      "offset_STD_seconds": -21600,
+      "offset_DST": "-05:00",
+      "offset_DST_seconds": -18000,
+      "abbreviation_STD": "CST",
+      "abbreviation_DST": "CDT"
+    },
+    "plus_code": "86CFWX65+45",
+    "plus_code_short": "65+45 Bethalto, Madison County, United States",
+    "rank": {
+      "importance": 0.35334333333333334,
+      "popularity": 1.6436670429679177,
+      "confidence": 1,
+      "confidence_city_level": 1,
+      "confidence_street_level": 1,
+      "match_type": "full_match"
+    },
+    "place_id": "518dddf41db28256c0591b608b8285744340f00102f90140194f0100000000c002049203104e6f727468204f616b20537472656574",
+    "bbox": {
+      "lon1": -90.0424917,
+      "lat1": 38.909672,
+      "lon2": -90.041749,
+      "lat2": 38.9110236
+    }
+  }
+}
+```
+
+If no result was found:
+
+```json
+{
+  "address": "Unknown Street",
+  "error": "No result found"
+}
+```
+
+## Read More
+
+- [Geoapify Geocoding API Documentation](https://www.geoapify.com/geocoding-api/)
+- [@geoapify/request-rate-limiter on npm](https://www.npmjs.com/package/@geoapify/request-rate-limiter)
+- [node-fetch Documentation](https://www.npmjs.com/package/node-fetch)
+- [Geoapify Developer Portal](https://apidocs.geoapify.com/)
+- [Rate Limiting and Batch Request Patterns (Blog)](https://www.geoapify.com/how-to-avoid-429-too-many-requests-with-api-rate-limiting/)
+
+For advanced use cases like CSV input/output, asynchronous job batching, or fallback handling, check the [Geoapify GitHub Examples](https://github.com/geoapify/maps-api-code-samples).

javascript/geocoding-with-RPS-limit-respect/geocode.js

@@ -0,0 +1,78 @@
+import fetch from 'node-fetch';
+import RequestRateLimiter from '@geoapify/request-rate-limiter';
+import fs from 'fs/promises';
+
+async function readAddressesFromFile(filename = 'input.txt') {
+    try {
+      const data = await fs.readFile(filename, 'utf-8');
+      return data
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.length > 0);
+    } catch (err) {
+      console.error(`❌ Failed to read ${filename}:`, err.message);
+      return [];
+    }
+  }
+
+const API_KEY = "YOUR_API_KEY";
+const GEOCODING_API_URL = 'https://api.geoapify.com/v1/geocode/search?limit=1&format=json';
+
+const createGeocodingRequest = (address) => {
+  return async () => {
+    try {
+      const url = `${GEOCODING_API_URL}&text=${encodeURIComponent(address)}&apiKey=${API_KEY}`;
+      const response = await fetch(url);
+      if (!response.ok) {
+        return { address, error: `HTTP error ${response.status}: ${response.statusText}` };
+      }
+
+      const data = await response.json();
+      if (data.results && data.results.length > 0) {
+        return { address, result: data.results[0] };
+      } else {
+        return { address, error: 'No result found' };
+      }
+    } catch (err) {
+      return { address, error: err.message };
+    }
+  };
+};
+
+async function geocodeBatch(addresses) {
+  const requests = addresses.map(createGeocodingRequest);
+
+  const options = {
+    batchSize: 10,
+    onProgress: (progress) => {
+      console.log(`Progress: ${progress.completedRequests}/${progress.totalRequests}`);
+    },
+    onBatchComplete: (batch) => {
+      console.log(`Batch completed (${batch.results.length}):`);
+      batch.results.forEach(r => {
+        console.log(r.result
+          ? `✅ ${r.address} → (${r.result.lat}, ${r.result.lon})`
+          : `❌ ${r.address} → ${r.error}`);
+      });
+    }
+  };
+
+  try {
+    const results = await RequestRateLimiter.rateLimitedRequests(requests, 5, 1000, options);
+    console.log('\n✅ All requests completed.');
+
+    return results;
+  } catch (err) {
+    console.error('❌ Error during batch geocoding:', err);
+  }
+}
+
+async function saveToJSONFile(results, filename = 'results.json') {
+    const json = JSON.stringify(results, null, 2);
+    await fs.writeFile(filename, json, 'utf-8');
+    console.log(`✅ Results saved to ${filename}`);
+}
+
+const addresses = await readAddressesFromFile();
+const results = await geocodeBatch(addresses);
+await saveToJSONFile(results);

javascript/geocoding-with-RPS-limit-respect/input.txt

@@ -0,0 +1,41 @@
+North Oak Street, Bethalto, IL 62010, USA,
+2809 College Avenue, Alton, IL 62002, USA,
+1 Lock and Dam Way, Alton, IL 62002, USA,
+40 West Ferguson Avenue, Wood River, IL 62095, USA,
+Illinois Route 111, Roxana, IL 62084, USA,
+715 North Main Street, Edwardsville, IL 62025, USA,
+620 Saint Louis Street, Edwardsville, IL 62025, USA,
+409 South Buchanan Street, Edwardsville, IL 62025, USA,
+722 Holyoake Road, Edwardsville, IL 62025, USA,
+1 Lewis and Clark Trail, Hartford, IL 62048, USA,
+Woodcrest Lane, Hazelwood, MO 63042, USA,
+14301 Creve Coeur Airport Road, Maryland Heights, MO 63146, USA,
+Plum Street, Collinsville, IL 62234, USA,
+4600 Labadie Avenue, St. Louis, MO 63115, USA,
+30 Ramey Street, Collinsville, IL 62234, USA,
+2505 Saint Louis Avenue, St. Louis, MO 63106, USA,
+2223 Saint Louis Avenue, St. Louis, MO 63106, USA,
+Westmoreland Avenue, Clayton, MO 63105, USA,
+1 Forsyth Boulevard, St. Louis, MO 63130, USA,
+5700 Lindell Boulevard, St. Louis, MO 63018, USA,
+650 Maryville University Drive, Town and Country, MO 63141, USA,
+4652 Maryland Avenue, St. Louis, MO 63108, USA,
+478 Covenat Lane, Creve Coeur, MO 63141, USA,
+3750 Washington Boulevard, St. Louis, MO 63108, USA,
+1 Fine Arts Drive, St. Louis, MO 63110, USA,
+2716 Doctor Martin Luther King Drive, St. Louis, MO 63106, USA,
+3441 Olive Street, St. Louis, MO 63103, USA,
+2660 Delmar Boulevard, St. Louis, MO 63103, USA,
+3415 Olive Street, St. Louis, MO 63103, USA,
+750 North 16th Street, St. Louis, MO 63103, USA,
+1508 Locust Street, St. Louis, MO 63103, USA,
+720 North 2nd Street, St. Louis, MO 63102, USA,
+615 Washington Avenue, St. Louis, MO 63101, USA,
+5050 Oakland Avenue, St. Louis, MO 63110, USA,
+1315 Chestnut Street, St. Louis, MO 63103, USA,
+1005 Pennsylvania Avenue, East St. Louis, IL 62201, USA,
+411 Locust Street, St. Louis, MO 63102, USA,
+1101 Macklind Avenue, St. Louis, MO 63110, USA,
+11 North 4th Street, St. Louis, MO 63101, USA,
+Gateway Arch Trail, St. Louis, MO 63102, USA,
+283 Lamp & Lantern Village, Town and Country, MO 63017, USA

javascript/geocoding-with-RPS-limit-respect/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "geocoding-with-rps-limit-respect",
+  "version": "1.0.0",
+  "main": "geocode.js",
+  "type": "module",
+  "scripts": {
+    "start": "node geocode.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "geocoding",
+    "geoapify",
+    "batch",
+    "rate-limit",
+    "node.js",
+    "api"
+  ],
+  "author": "Geoapify",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "@geoapify/request-rate-limiter": "^1.0.1",
+    "node-fetch": "^3.3.2"
+  }
+}