BLOCK COORDINATES TOOLKIT — PropEase / study24.in
=======================================================

THREE COMPLEMENTARY TOOLS, ONE SHARED DATABASE
------------------------------------------------

  block_verify.php   ⭐ PRIMARY — manual verification via Google Maps
  block_coords.php      Bulk — upload an Excel of blocks, get coords back
  block_map.php         Map UI — drag pins to reposition (less accurate than block_verify)

All three read and write the same blocks_db.json file.


FILES IN THIS PACKAGE
---------------------
  block_verify.php    Manual verification tool (recommended)
  block_coords.php    Excel upload/enrich tool
  block_map.php       Leaflet map viewer / editor
  blocks_db.json      Shared database — 531 Bihar blocks pre-seeded
  README.txt          This file
  sample_input.xlsx   Example input for block_coords.php


RECOMMENDED WORKFLOW (HIGHEST ACCURACY)
---------------------------------------

1. Upload all three PHP files + blocks_db.json to Namecheap:
     public_html/block-tool/block_verify.php
     public_html/block-tool/block_coords.php
     public_html/block-tool/block_map.php
     public_html/block-tool/blocks_db.json

2. Set permissions:
     *.php              644 (default)
     blocks_db.json     664   (must be writable by PHP — try 666 if 664 fails)

3. Open block_verify.php. Work through one district at a time:
     - Pick district from dropdown (shows progress like "Patna (3/23 verified)")
     - For each block, click "Search" → Google Maps opens in a new tab
     - Find the block HQ / BDO office on the map
     - Copy the URL (Ctrl+L, Ctrl+C) → paste into the input field
     - Press Enter → saves, auto-jumps to next block

   Each district takes ~3-5 minutes. All 38 districts: ~2 hours total.
   Fully optional — you can do it gradually over days/weeks.

4. When you need coords in a spreadsheet, use block_coords.php:
     - Upload your Excel of districts+blocks
     - Get back a file with all the verified coords already filled
     - Blocks you haven't verified yet will show the seed data (±2-10 km)

5. Click "Download Excel" inside block_verify.php any time to get
   the full 531-block list with current coordinates.


HOW block_verify.php PARSES COORDINATES
----------------------------------------

When you paste into the input field, these formats all work automatically:

  OK: Google Maps URL       https://www.google.com/maps/place/Bihta/@25.5433,85.0521,17z
  OK: Maps data URL         https://www.google.com/maps/.../!3d25.5433!4d85.0521
  OK: Plain decimal         25.5433, 85.0521
  OK: Space-separated       25.5433 85.0521
  OK: DMS                   25°32'36"N 85°03'08"E

  NO: Short links           https://maps.app.goo.gl/abc123
    (First open the short link in a browser, then copy the expanded URL.)


KEYBOARD SHORTCUTS (block_verify.php)
-------------------------------------

  Enter     Save current row + auto-focus next unverified row
  N         Jump to next unverified row (from anywhere not an input)
  Tab       Move between inputs


INSTALLATION CHECKLIST
----------------------

[ ] Uploaded all 4 files (3 PHP + 1 JSON)
[ ] Set blocks_db.json to 664 or 666
[ ] Opened block_coords.php → clicked "Run server diagnostics" →
    verified ZipArchive, cURL, mbstring all say `true`
[ ] Tested with sample_input.xlsx — got back enriched file
[ ] Opened block_verify.php — saved one test block, verified the
    "Verified" badge appears and persists after a page reload


TROUBLESHOOTING
---------------

Problem: "Could not write blocks_db.json"
  Fix: chmod 666 blocks_db.json (or 664 on some hosts)

Problem: Save silently fails
  Fix: Open block_coords.php → "Run server diagnostics" link at bottom
       Look for "db_file_writable": false → fix permissions

Problem: Saves work but the Excel download still shows old coordinates
  Fix: Hard-refresh the browser (Ctrl+Shift+R). The file is regenerated
       fresh every download — it's never cached.

Problem: "Unexpected token '<'" error
  Fix: Use the diagnostics endpoint in block_coords.php to see what
       PHP is actually returning. Common causes: missing extension,
       mod_security, file size over post_max_size.


ACCURACY EXPECTATIONS
---------------------

Source labels in the exported Excel:

  Seed (postal data)     Initial coordinates from postal-code centroids
                         ~2-10 km error; imperfect but usable as a starting point

  OpenStreetMap          Auto-geocoded via Nominatim from block_coords.php
                         Usually ~100-500m from actual HQ

  Manually verified      You confirmed this on Google Maps
                         Accurate to whatever precision you chose on the map


SHARED DATA MODEL
-----------------

blocks_db.json stores each block as:

  "patna|bihta": {
      "d": "Patna",
      "b": "Bihta",
      "lat": 25.54333,
      "lon": 85.05207,
      "c": "high",                          // high / medium / low / approx
      "s": "manual",                        // seed / osm / manual
      "m": "Verified 2026-04-21 15:20"      // notes
  }

Source precedence: manual > osm > seed. Once s="manual", no automatic
tool will overwrite it — your manual verifications are protected.


CONTACT
-------
Platform: Ravi Kumar — KUMARR260@gmail.com

---
Built April 2026 for study24.in / PropEase.
Uses Google Maps (external) for HQ verification; OpenStreetMap via
Nominatim as auto-geocoding fallback.
