Datafiniti.Sdk 0.1.5

Datafiniti.Sdk (C#)

A unified C# SDK for Datafiniti's four data types: Business, People, Property, and Product. This is a C# port of the Python datafiniti-sdk, preserving the same architecture: a shared HTTP base, per-type clients, and fluent query builders.

Layout

Datafiniti/
├── Datafiniti.sln
├── src/
│   ├── Datafiniti.Sdk/
│   │   ├── Core/               ← shared base client, retry, errors, query builder
│   │   │   ├── DatafinitiClientBase.cs
│   │   │   ├── DatafinitiClientOptions.cs
│   │   │   ├── DatafinitiApiException.cs
│   │   │   ├── QueryBuilder.cs
│   │   │   ├── SearchRequest.cs
│   │   │   └── SearchResult.cs
│   │   ├── Business/           ← BusinessClient + BusinessQuery
│   │   ├── People/             ← PeopleClient + PeopleQuery
│   │   ├── Property/           ← PropertyClient + PropertyQuery
│   │   └── Product/            ← ProductClient + ProductQuery
│   └── Datafiniti.Examples/    ← runnable console examples
└── tests/
    └── Datafiniti.Sdk.Tests/   ← xUnit tests (query building + retry)

Architecture mapping (Python → C#)

Usage

using Datafiniti.Business;
using Datafiniti.Property;

using var business = BusinessClient.FromEnvironment(); // reads DATAFINITI_API_KEY

// Count
var count = await business.CountAsync(
    new BusinessQuery().Country("US").Categories("Restaurant").Build());

// Search
var result = await business.SearchAsync(
    new BusinessQuery().Country("US").City("Austin").Build(), numRecords: 25);

// Paginate — streams every matching record
var query = new BusinessQuery().Country("US").Province("TX").Build();
await foreach (var record in business.PaginateAsync(query))
{
    // record is a System.Text.Json.JsonElement
}

// Geolocation — radius search around Austin, TX
var near = await business.GeoLocationAsync(-97.7430600, 30.2671500, 10, "mi");

Property example:

using var property = PropertyClient.FromEnvironment();

var query = new PropertyQuery()
    .Country("US")
    .PostalCode("78722")
    .MostRecentStatus("For Sale")
    .Build();
// country:US AND postalCode:"78722" AND mostRecentStatus:("For Sale")

var listings = await property.SearchAsync(query);

PropertyQuery.Address() (and the SearchByAddressAsync() convenience method) query the address field, which Datafiniti fuzzy-matches — a partial address (e.g. missing city, state, or ZIP) can still match full records. See Fuzzy Matching for the exact rules (address must start with a house number, US-only, and pre-existing city/province/postalCode filters are never overwritten).

Configuration

Set your API key via environment variable:

export DATAFINITI_API_KEY="your-key"

Or construct options directly:

var options = new DatafinitiClientOptions
{
    ApiKey = "your-key",
    MaxRetries = 3,
    InitialBackoff = TimeSpan.FromSeconds(1),
};
using var client = new BusinessClient(options);

Running the examples

Datafiniti.Examples runs one example against each data type — Business (count, geolocation, paginate), People (search), Property (search), and Product (search):

dotnet run --project src/Datafiniti.Examples

To print each outgoing request's method, URL, and JSON body to the console (useful when an API call comes back with a 400), set DATAFINITI_LOG_REQUESTS:

export DATAFINITI_LOG_REQUESTS=1   # bash
$env:DATAFINITI_LOG_REQUESTS=1     # PowerShell
dotnet run --project src/Datafiniti.Examples

This is wired up via a RequestLoggingHandler in the Examples project only — it isn't part of the SDK's public API.

Retry behavior

Requests are retried with exponential backoff (1s → 2s → 4s) on HTTP status codes 408, 429, 500, 502, 503, 504, and on transient network failures — matching the Python SDK. Non-retryable errors throw DatafinitiApiException immediately.

Build & test

dotnet build
dotnet test

VS Code

Install the .NET SDK 8.0 and the C# Dev Kit extension. Open the folder, and the Test Explorer (flask icon) will discover the xUnit tests. Run Datafiniti.Examples with F5 after setting DATAFINITI_API_KEY (and optionally DATAFINITI_LOG_REQUESTS, see Running the examples).

Roadmap (from the Python SDK)

• Phase 2: typed response models per data type, download jobs, custom views
• Phase 3: CLI, address normalization (Property), price normalization (Product)
• Error subclasses: RateLimitException, AuthenticationException, ValidationException