Node.js - Property Data SDK

import { PropertyClient } from "datafiniti-sdk";

const sdk = PropertyClient.fromEnv();

const response = await sdk.searchByAddress("712 liard river rd", {
  postalCode: "78634",
});

console.log("
=== ADDRESS SEARCH TEST ===");
console.log("Matches:", response.num_found);

const records = response.records ?? [];

if (records.length) {
  const property = records[0];
  console.log("
Property:");
  console.log(property.address);
  console.log(property.city);
  console.log(property.province);
} else {
  console.log("No property found.");
}

import { PropertyClient } from "datafiniti-sdk";

const sdk = PropertyClient.fromEnv();

const count = await sdk.count('country:US AND mostRecentStatus:"For Sale"');

console.log("
=== COUNT TEST ===");
console.log(`Properties found: ${count.toLocaleString()}`);

import { PropertyClient } from "datafiniti-sdk";

const sdk = PropertyClient.fromEnv();

// Search for properties within 10 miles of downtown Austin, TX
// geoLocation format: [Longitude, Latitude, Distance, Unit]
// Supported units: m, mi, ft, yd, mm, km, NM, cm
const response = await sdk.geolocation({
  longitude: -97.7430600,
  latitude: 30.2671500,
  distance: 10,
  unit: "mi",
  numRecords: 5,
  view: [
    { name: "address" },
    { name: "city" },
    { name: "country" },
    { name: "geoLocation" },
    { name: "mostRecentStatus" },
    { name: "mostRecentStatusDate" },
    { name: "mostRecentStatusFirstDateSeen" },
    { name: "postalCode" },
  ],
});

console.log("
=== GEOLOCATION SEARCH ===");
console.log(`Total matches: ${(response.num_found ?? 0).toLocaleString()}`);

const records = response.records ?? [];

for (const prop of records) {
  console.log(
    `
${prop.address}, ${prop.city} ${prop.postalCode}` +
      ` — ${prop.mostRecentStatus}` +
      `
--geoLocation: ${prop.geoLocation}`
  );
}

import { PropertyClient } from "datafiniti-sdk";

const sdk = PropertyClient.fromEnv();

console.log("
=== PAGINATION TEST ===");

let recordsSeen = 0;

for await (const property of sdk.paginate({
  query: "country:US",
  pageSize: 10,
  maxRecords: 25,
})) {
  recordsSeen += 1;
  console.log(`${recordsSeen}. ${property.address ?? "Unknown Address"}`);
}

console.log(`
Total Retrieved: ${recordsSeen}`);

/**
 * Property Views Example: E-Commerce Vacant House Check
 *
 * Uses a custom view to fetch only the fields needed to determine whether a
 * shipping address matches a vacant or off-market property — a common signal
 * for potentially fraudulent e-commerce orders.
 *
 * Reference: https://docs.datafiniti.co/docs/identify-e-commerce-orders-shipping-to-vacant-houses
 */

import { PropertyClient, type DatafinitiRecord } from "datafiniti-sdk";

// ---------------------------------------------------------------------------
// View options
//
// OPTION 1 (used below): Custom inline view
//   Pass an array of field objects directly in the request. No setup required.
//   Reference: https://docs.datafiniti.co/docs/using-a-custom-property-view
//
// OPTION 2: Premade (named) view — pass a string instead of an array.
//   "default"               All fields (same as omitting view entirely).
//                           Note: imageURLs and sourceURLs are excluded from
//                           default; use a preset or custom view for those.
//   "property_flat_prices"  All fields; one CSV row per price entry.
//   "property_flat_reviews" All fields; one CSV row per review.
//   "residential"           Residential-focused fields — includes absenteeOwner,
//                           assessedValues, ownerName, statuses, transactions, etc.
//   Example: sdk.search({ query, view: "residential", numRecords: 10 })
//   Reference: https://docs.datafiniti.co/docs/available-views-for-property-data
// ---------------------------------------------------------------------------

const PROPERTY_VIEW = [
  { name: "address" },
  { name: "city" },
  { name: "province" },
  { name: "postalCode" },
  { name: "mostRecentStatus" },
  { name: "mostRecentStatusDate" },
  { name: "mostRecentRentalStatus" },
  { name: "mostRecentRentalStatusDate" },
];

const ON_MARKET_STATUSES = new Set([
  "For Sale",
  "Coming Soon",
  "Pending",
  "For Rent",
  "For Sale or Rent",
]);

function marketStatus(record: DatafinitiRecord): [string, string] {
  const sale = (record.mostRecentStatus as string) ?? "";
  const rental = (record.mostRecentRentalStatus as string) ?? "";
  if (ON_MARKET_STATUSES.has(sale)) {
    return ["On Market", (record.mostRecentStatusDate as string) ?? "N/A"];
  }
  if (ON_MARKET_STATUSES.has(rental)) {
    return ["On Market", (record.mostRecentRentalStatusDate as string) ?? "N/A"];
  }
  const date =
    (record.mostRecentStatusDate as string) ||
    (record.mostRecentRentalStatusDate as string) ||
    "N/A";
  return ["Off Market", date];
}

async function checkAddress(
  sdk: PropertyClient,
  address: string,
  city: string,
  province: string,
  postalCode: string
): Promise<DatafinitiRecord | null> {
  const query = sdk
    .query()
    .address(address)
    .city(city)
    .province(province)
    .postalCode(postalCode)
    .country("US")
    .build();

  const response = await sdk.search({ query, numRecords: 1, view: PROPERTY_VIEW });
  const records = response.records ?? [];
  return records.length ? records[0] : null;
}

async function main() {
  // Sample shipping addresses from incoming orders.
  // Normalize street designations before querying — Datafiniti uses
  // abbreviations: "Ave" not "Avenue", "St" not "Street", "Dr" not "Drive".
  const addresses = [
    { address: "200 Tennyson Ave",        city: "Pittsburgh", province: "PA", postalCode: "15213" },
    { address: "4616 Howard Ln UNIT 550", city: "Austin",     province: "TX", postalCode: "78728" },
    { address: "1023 Grassy Field Rd",    city: "Austin",     province: "TX", postalCode: "78737" },
  ];

  const sdk = PropertyClient.fromEnv();

  console.log("
=== VACANT HOUSE CHECK ===
");

  for (const entry of addresses) {
    console.log(`${entry.address}, ${entry.city}, ${entry.province} ${entry.postalCode}`);

    const record = await checkAddress(
      sdk,
      entry.address,
      entry.city,
      entry.province,
      entry.postalCode
    );

    if (record === null) {
      console.log("  No property record found.
");
      continue;
    }

    const [label, date] = marketStatus(record);
    console.log(`  ID:                    ${record.id ?? "N/A"}`);
    console.log(`  Address:               ${record.address ?? "N/A"}`);
    console.log(`  City:                  ${record.city ?? "N/A"}`);
    console.log(`  Province:              ${record.province ?? "N/A"}`);
    console.log(`  Postal Code:           ${record.postalCode ?? "N/A"}`);
    console.log(`  Most Recent Status:    ${record.mostRecentStatus ?? "N/A"}`);
    console.log(`  Most Recent Rental:    ${record.mostRecentRentalStatus ?? "N/A"}`);
    console.log(`  Status: ${label} (as of ${date})`);
    if (label === "Off Market") {
      console.log("  *** FLAGGED — property may be vacant ***");
    }
    console.log();
  }
}

main();

import { PropertyClient } from "datafiniti-sdk";

const sdk = PropertyClient.fromEnv();

const view = [
  { name: "address" },
  { name: "city" },
  { name: "province" },
  { name: "postalCode" },
  { name: "mlsNumber" },
  { name: "mostRecentStatus" },
  { name: "mostRecentSaleListPriceAmount" },
  { name: "brokers" },
];

const singleQuery = 'country:US AND province:IL AND mlsNumber:"09073511"';
const singleResponse = await sdk.search({
  query: singleQuery,
  numRecords: 1,
  view,
});

console.log("
=== SINGLE MLS SEARCH ===");
console.log("Matches:", singleResponse.num_found);

const singleRecords = singleResponse.records ?? [];

for (const property of singleRecords) {
  const brokers = Array.isArray(property.brokers)
    ? property.brokers.map((broker) => broker?.agent).filter(Boolean).join(", ")
    : "N/A";

  console.log(`
${property.address}, ${property.city}, ${property.province} ${property.postalCode}`);
  console.log(`MLS Number: ${property.mlsNumber ?? "N/A"}`);
  console.log(`Status: ${property.mostRecentStatus ?? "N/A"}`);
  console.log(`List Price: ${property.mostRecentSaleListPriceAmount ?? "N/A"}`);
  console.log(`Agents: ${brokers || "N/A"}`);
}

const advancedQuery =
  "country:US AND people.title:owner AND prices.amountMin:>=500000 AND brokers.agent:* AND province:IL AND mlsNumber:(09073511 OR 09505465)";
const advancedResponse = await sdk.search({
  query: advancedQuery,
  numRecords: 10,
  view,
});

console.log("
=== MULTI MLS SEARCH WITH FILTERS ===");
console.log("Matches:", advancedResponse.num_found);

const advancedRecords = advancedResponse.records ?? [];

for (const property of advancedRecords) {
  const brokers = Array.isArray(property.brokers)
    ? property.brokers.map((broker) => broker?.agent).filter(Boolean).join(", ")
    : "N/A";

  console.log(`
${property.address}, ${property.city}, ${property.province} ${property.postalCode}`);
  console.log(`MLS Number: ${property.mlsNumber ?? "N/A"}`);
  console.log(`Status: ${property.mostRecentStatus ?? "N/A"}`);
  console.log(`List Price: ${property.mostRecentSaleListPriceAmount ?? "N/A"}`);
  console.log(`Agents: ${brokers || "N/A"}`);
}

import { PropertyClient, DatafinitiApiError } from "datafiniti-sdk";

const sdk = PropertyClient.fromEnv();

try {
  const response = await sdk.search({ query: "country:US", numRecords: 5 });
  console.log(`Matches: ${response.num_found}`);
} catch (err) {
  if (err instanceof DatafinitiApiError) {
    console.error(`API error ${err.statusCode}: ${err.message}`, err.errors);
  } else {
    throw err;
  }
}