SmartLocator API key

1. Submit a test file

CSV, XLSX or XLS · current API limit 2,000 rows.

2. Job status

No job selected.

Privacy: activity logs contain event metadata only. Address values, CSV rows, order details, API keys, tokens and raw request/response bodies are not stored here. Only your authenticated account's events are returned.

1. Single address verification

Run this from a trusted server or terminal. The request fields match the official API reference.

cURL

curl -X POST "https://smartlocator.online/api/single-verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "Flat 204, Green Park Apartments, Sector 45, Gurugram, Haryana 122003",
    "customerName": "Ravi Kumar"
  }'

Node.js (server-side)

const response = await fetch("https://smartlocator.online/api/single-verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SMARTLOCATOR_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    address: "Flat 204, Green Park Apartments, Sector 45, Gurugram, Haryana 122003",
    customerName: "Ravi Kumar"
  })
});

const raw = await response.text();
let result;
try { result = JSON.parse(raw); } catch { result = { message: raw }; }

if (!response.ok) {
  const detail = result.message || result.error || result.detail ||
    `HTTP ${response.status}`;
  throw new Error(`SmartLocator request failed: ${detail}`);
}
console.log(result);

Handle the actual JSON fields returned by your account's response; avoid assuming fields not present in the response.

2. Google Sheets with Apps Script

Example: read an address from column A and write the HTTP status plus result JSON into columns B and C. Set a script property named SMARTLOCATOR_API_KEY under Apps Script project settings before running.

function verifySelectedAddress() {
  const apiKey = PropertiesService.getScriptProperties()
    .getProperty('SMARTLOCATOR_API_KEY');
  if (!apiKey) throw new Error('Set SMARTLOCATOR_API_KEY in Script Properties.');

  const sheet = SpreadsheetApp.getActiveSheet();
  const row = sheet.getActiveCell().getRow();
  if (row < 2) throw new Error('Select an address row below the header.');
  const address = String(sheet.getRange(row, 1).getDisplayValue()).trim();
  if (!address) throw new Error('Column A has no address.');

  const response = UrlFetchApp.fetch(
    'https://smartlocator.online/api/single-verify',
    {
      method: 'post',
      contentType: 'application/json',
      headers: { Authorization: 'Bearer ' + apiKey },
      payload: JSON.stringify({ address: address }),
      muteHttpExceptions: true
    }
  );
  const status = response.getResponseCode();
  const body = response.getContentText();
  let parsed;
  try { parsed = JSON.parse(body); } catch (e) { parsed = null; }
  sheet.getRange(row, 2).setValue(status);
  // Preserve the upstream error message when available; otherwise keep the body.
  const display = status >= 200 && status < 300
    ? (parsed ? JSON.stringify(parsed) : body)
    : ((parsed && (parsed.message || parsed.error || parsed.detail)) ||
       body || ('Request failed with HTTP ' + status));
  sheet.getRange(row, 3).setValue(String(display).slice(0, 45000));
}

This one-row helper is a starter example, not a high-volume batch runner. Add backoff, quotas and retry handling before processing large sheets.

3. Build your own customer dashboard

Recommended architecture: browser UI → your own backend endpoint → SmartLocator API. Your backend stores the secret key and returns only the result your UI needs.

Browser-side UI (calls your backend, not SmartLocator directly)

async function verifyAddress() {
  const address = document.querySelector('#address').value.trim();
  const button = document.querySelector('#verify');
  const output = document.querySelector('#result');
  if (!address) { output.textContent = 'Enter an address.'; return; }

  button.disabled = true;
  output.textContent = 'Verifying…';
  try {
    // This is YOUR backend route, which securely calls SmartLocator.
    const response = await fetch('/api/verify-address', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ address })
    });
    const result = await response.json();
    if (!response.ok) throw new Error(result.message || 'Verification failed');
    output.textContent = JSON.stringify(result, null, 2);
  } catch (error) {
    output.textContent = error.message || 'Unable to verify address.';
  } finally {
    button.disabled = false;
  }
}

The /api/verify-address route is an example you must implement on your own server. Do not deploy this UI alone and expect the placeholder route to exist.

4. Bulk CSV workflow

Bulk processing is asynchronous. Submit the CSV from your backend, persist the returned job ID, poll with a reasonable interval, stop when terminal, then download the output.

const base = 'https://smartlocator.online';
const headers = {
  Authorization: `Bearer ${process.env.SMARTLOCATOR_API_KEY}`,
  'Content-Type': 'application/json'
};

const submit = await fetch(base + '/api/bulk-jobs', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    filename: 'orders.csv',
    totalRows: 1,
    csvData: 'ORDER ID,CUSTOMER NAME,CUSTOMER RAW ADDRESS\\n1001,Ravi Kumar,DLF Phase 1 Gurgaon 122002'
  })
});
const submitText = await submit.text();
let created;
try { created = JSON.parse(submitText); } catch { created = { message: submitText }; }
if (!submit.ok || !created.jobId) {
  const detail = created.message || created.error || created.detail ||
    `HTTP ${submit.status}`;
  throw new Error(`Bulk submission failed: ${detail}`);
}
const jobId = created.jobId;

// Poll no faster than every 5–10 seconds; use a sensible overall timeout.
let job;
for (let attempt = 0; attempt < 60; attempt++) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  const statusResponse = await fetch(base + '/api/bulk-jobs', {
    headers: { Authorization: headers.Authorization }
  });
  const statusData = await statusResponse.json();
  if (!statusResponse.ok) throw new Error('Could not load jobs');
  job = (statusData.jobs || []).find(item => String(item._id) === String(jobId));
  if (!job) throw new Error('Job not found for this account');
  if (['Completed', 'Failed', 'Cancelled'].includes(job.status)) break;
}
if (!job || job.status !== 'Completed') {
  throw new Error('Job did not complete successfully within the example timeout');
}
const ready = await fetch(
  base + '/api/bulk-jobs?action=download&jobId=' +
  encodeURIComponent(jobId) + '&type=ready',
  { headers: { Authorization: headers.Authorization } }
);
if (!ready.ok) {
  const detail = await ready.text();
  throw new Error('Ready CSV download failed: ' + (detail || `HTTP ${ready.status}`));
}
const readyCsv = await ready.text();
console.log('Ready CSV characters:', readyCsv.length);

// To download Manual output instead, use type=manual in the same URL.
// Check the job's terminal status before requesting either output.

Confirm the actual job response fields and available download types in the official reference. Respect account plan limits and do not retry job submission blindly after an uncertain network timeout.

5. Errors and troubleshooting

Read the HTTP status and the API response body together. The examples below describe common situations; exact status codes and wording can depend on the endpoint and account state. Prefer the actual message or error returned by SmartLocator over a hard-coded assumption.

Example: show the API's actual error message (Node.js)

const response = await fetch(url, options);
const raw = await response.text();
let data;
try { data = JSON.parse(raw); } catch { data = { message: raw }; }

if (!response.ok) {
  const message = data.message || data.error || data.detail ||
    `Request failed with HTTP ${response.status}`;
  throw new Error(message);
}

This is a general response-handling pattern, not a promise that every endpoint uses the same error fields. Do not log API keys, addresses, CSV contents, or other sensitive request data when reporting errors.

Generate a report after running tests.

Request History