GeoSurvey · Setup guide
1 / 13
Step-by-step · about 5 minutes, once

Set up GeoSurvey for your team

One Google Sheet becomes the database. Phones connect by scanning a QR code. AI photo-fill is optional and can be switched on for the whole team with a single key. This guide shows every click.

1 · Google SheetApps Script · 4 min · once
→
2 · Connect phonesscan a QR · seconds each
→
3 · AI (optional)one free key · 1 min

You need: a Google account, a computer for step 1, and the phones that will collect data. Use → / ← or swipe to move between slides.

After step 1 the backend keeps itself up to date — you never paste code or press “New version” again.
Step 1 · part A 1 min

Create the Google Sheet and open Apps Script

  1. 1Go to sheets.new — a new Google Sheet opens. Name it, e.g. Village Survey 2026.
  2. 2In the menu click Extensions → Apps Script. A code page opens in a new tab.
  3. 3Delete all the text in that code page (select all, delete).
docs.google.com/spreadsheets/… Village Survey 2026
FileEditViewInsertFormatDataToolsExtensionsHelp
Add-ons ›Macros ›Apps ScriptAppSheet ›
Step 1 · part B 2 min

Paste the code and the manifest; set the team key

  1. 1Open github.com/pulakeshpradhan/geosurvey → folder backend → Code.gs → copy icon. Paste into the empty code page.
  2. 2Click the gear (Project Settings) on the left → tick Show “appsscript.json” manifest file in editor. Back in the editor (< >) click appsscript.json, delete its text and paste backend/appsscript.json from GitHub.
  3. 3In Code.gs find var ADMIN_TOKEN = 'GeoSurvey'; — this is the team key. Keep it for a trial; for a real project replace GeoSurvey with your own key (keep the quotes).
  4. 4Press Ctrl+S to save.
The team key unlocks “Sync all”, “Edit” and deleting records. Enumerators who only collect data never need it.
script.google.com · Code.gs
var BACKEND_VERSION = '1.16.0'; var AI_KEY = ''; // optional, step 3 var ADMIN_TOKEN = 'GeoSurvey'; // team key var SHEET_NAME = 'Responses'; …
Code.gsappsscript.json
💾 Save (Ctrl+S)
Step 1 · part C 1 min

Switch on the Apps Script API, then allow access

  1. 1Open script.google.com/home/usersettings and switch Google Apps Script API to On. (This only lets your own script update itself; it exposes nothing.)
  2. 2Back in the editor: the dropdown next to ▶ Run says myFunction or doPost. Change it to authorizeDrive and click ▶ Run.
  3. 3“Authorization required”: Review permissions → your account → Advanced → Go to … (unsafe) → Allow. (Google says “unsafe” for every personal script — it is your own code.)
  4. 4The log shows “Drive authorised” with a link to the new Drive folder GeoSurvey Photos, and “Publish: …”.
Do not skip this. Without it photos and recordings are not stored and the backend cannot update itself.
script.google.com · Code.gs
▶ RunDebugauthorizeDrive ▾
Authorization requiredThis project needs your permission to access your data.
CancelReview permissions
Google hasn’t verified this appAdvanced → Go to GeoSurvey (unsafe)
Allow
Execution log: Drive authorised. Folder: drive.google.com/… · Publish: {"ok":true,…}
Step 1 · part D 1 min

Publish the script and copy its address

  1. 1Click Deploy (top right) → New deployment.
  2. 2Click the gear icon next to “Select type” and choose Web app.
  3. 3Set Execute as: Me and Who has access: Anyone. Click Deploy.
  4. 4Click Copy under Web app URL. It ends with /exec.
This is the last time you touch Apps Script. New versions install themselves; the URL never changes. Treat the URL like a key — share it only with your team.
script.google.com · New deployment
Deploy ▾New deployment
New deployment
Type
Web app
Execute as
Me (you@gmail.com)
Who has access
Anyone
Deploy
Web app URL
https://script.google.com/macros/s/AKfy…/exec
Copy
Step 2 seconds per phone

Connect the phones

  1. 1On your own phone or computer: open pulakeshpradhan.github.io/geosurvey, tap ⚙️, paste the Web app URL into Database endpoint, tap Test database → Backend OK → Save.
  2. 2Tap the QR icon in the top bar. A code appears.
  3. 3Each enumerator points their phone camera at it and opens the link. Their phone is now connected — nothing to type. (Or Copy link and send it on WhatsApp.)
  4. 4On each phone: ⚙️ → type the Enumerator name, choose the Interview language, Save. Add the app to the home screen.
The QR / link contains the database address. Share it only with your enumerators.
pulakeshpradhan.github.io/geosurvey · Team link
Database endpoint
https://script.google.com/macros/s/AKfy…/exec
Test databaseBackend v1.16.0 OK · Drive folder ready
Team linkPoint the phone camera at this code
Copy linkShare…Close
Step 3 · optional 1 min

Switch on AI photo-fill for the whole team

  1. 1Open aistudio.google.com/app/apikey, sign in, Create API key, Copy (starts with AIza). Free.
  2. 2In Apps Script, Code.gs: find var AI_KEY = ''; and paste the key between the quotes. Ctrl+S.
  3. 3In the dropdown next to ▶ Run choose updateBackend → ▶ Run. Done: every connected phone now has Analyze & fill (Google’s Gemma 4), with no key on the phone.
Alternative for one phone only: ⚙️ → Gemini API key → Test connection → Save. Voice recordings need this option.
script.google.com · Code.gs
var BACKEND_VERSION = '1.16.0'; var AI_KEY = 'AIzaSyD4f…9xQ'; // team AI key var ADMIN_TOKEN = 'GeoSurvey'; …
▶ RunupdateBackend ▾
Execution log: {"ok":true,"updated":false,"version":"1.16.0","deployments":1}
Step 4 1 min

Choose the questionnaire

The first time, the app asks how to start. Pick one (needs the team key once a database is connected):

  1. AUse sample questionnaire — a complete household survey. Fastest way to begin.
  2. BDesign your own — add sections and questions like Google Forms.
  3. CUpload paper questionnaire — PDF or photos of your printed form; it is converted exactly as printed. Then Improve with AI if you want.
  4. DOpen a project file — a .geosurvey file installs the questionnaire and connects the phone to the database. Every Publish saves one to the Drive folder automatically.

Change it any time with the Edit button (team key). Apply = this phone. Publish to team = every phone gets it.

GeoSurvey · Survey
Start your questionnaire
✎ Design your ownSections and questions, form-style.
▤ Use sample questionnaireHousehold survey with 5 perception constructs.
⇪ Upload paper questionnairePDF / photos → converted as printed.
In the field

One household in five steps

  1. 1Location fills itself. Wait until it shows e.g. ±8 m. Village, block and PIN come from the map — correct them if wrong.
  2. 2Capture photo the house, kitchen, water source, ID or paper form; Record the interview in any language; or tap ✎ to type notes.
  3. 3Analyze & fill — the AI fills the answers in English. Answers in yellow are AI-filled: check and correct.
  4. 4Each section has its own 📷 ✨ 🎙 buttons. Recording with a section mic fills that section as soon as you stop.
  5. 5Submit. Sent to the Sheet; no internet → sent later by itself. PDF prints an A4 copy.
Photos & auto-fill
📷 Capture photo🎙 Record✎
Analyze & fill
01 · LocationBaidyapur, Kalna II, Purba Bardhaman, 713122 · ±8 m
02 · Household headName
Sita MondalAge
42
Submit
Where everything is saved

Your data stays in your Google account

Phoneonly a queue: records wait here until sent, then the copy is removed
→
Google Sheetone row per household, tab “Responses”
+
Drive folder “GeoSurvey Photos”photos, recordings, transcripts; links in the Sheet

Records tab: Sync sends what is waiting and shows your records straight from the database. Sync all shows everyone’s — it asks for the team key once. Rows marked database come from other phones. Files in Drive shows links, or Upload files if a photo did not arrive. The Drive folder also holds Rows marked database come from other phones. Files in Drive shows links, or Upload files if a photo did not arrive.

lt;titleRows marked database come from other phones. Files in Drive shows links, or Upload files if a photo did not arrive.

gt;.geosurvey, a project file that restores the questionnaire and connection on any phone.

Downloads: Records → CSV, JSON, SPSS (.sav), KMZ (Google Earth). Analysis tab → automatic statistics and a plain-language report. Data (header button, team key) → every submission from every phone, with statistics, exports and delete.

If something does not work

Quick fixes

You seeDo this
“Backend is older than the app”Settings → Test database updates it. “Apps Script API is off” → step 1C.1. “Not authorised” → steps 1B.2 and 1C.2. A backend older than v1.15.4 needs Code.gs pasted once more (steps 1B–1D).
“AI error” / “backend has no AI key”Step 3: paste the key into AI_KEY and run updateBackend. Per-phone key: Settings → Test connection.
“permission to call DriveApp”Step 1C was skipped: run authorizeDrive and Allow, then Records → Upload files.
“Team key not accepted”It must match ADMIN_TOKEN in Code.gs exactly (capital letters matter).
“Locating…” never finishesAllow location when the phone asks; move near a window or outside; tap ⟳ Refresh.
Camera or microphone does not openAllow camera and microphone for the site in the phone’s browser settings.
App looks old after an updateClose it completely and open again.
Before the first day of fieldwork

Checklist

That’s it. Open pulakeshpradhan.github.io/geosurvey and start.

Reference

Links you will need

WhatWhere
The apphttps://pulakeshpradhan.github.io/geosurvey/
New Google Sheethttps://sheets.new
Backend code to pastehttps://github.com/pulakeshpradhan/geosurvey/blob/main/backend/Code.gs
Manifest to pastehttps://github.com/pulakeshpradhan/geosurvey/blob/main/backend/appsscript.json
Apps Script API switchhttps://script.google.com/home/usersettings
Free AI key (optional)https://aistudio.google.com/app/apikey
Written guidehttps://github.com/pulakeshpradhan/geosurvey#readme

Print all slides (top right) gives a one-page-per-step handout. Created by Pulakesh Pradhan.