vynco

Rust SDK for the VynCo Swiss Corporate Intelligence API.

Access 320,000+ Swiss companies from the Zefix commercial registry with full-text search, change tracking, relationship mapping, AI-generated dossiers, and advanced analytics.

Installation

[dependencies]
vynco = "1.0"

For the synchronous (blocking) client:

[dependencies]
vynco = { version = "1.0", features = ["blocking"] }

Quick Start

use vynco::{Client, CompanyListParams};

#[tokio::main]
async fn main() -> Result<(), vynco::VyncoError> {
    let client = Client::builder("vc_live_your_api_key")
        .build()?;

    // List companies with filtering
    let params = CompanyListParams {
        search: Some("Novartis".into()),
        canton: Some("BS".into()),
        ..Default::default()
    };
    let resp = client.companies().list(&params).await?;
    println!("Found {} companies", resp.data.total_count);
    println!("Credits used: {:?}", resp.meta.credits_used);

    // Get company by UID
    let company = client.companies().get("CHE-100.023.968").await?;
    println!("{}: {}", company.data.name, company.data.purpose);

    // Full-text search (FTS5)
    let results = client.companies().search(&vynco::CompanySearchRequest {
        query: "pharma".into(),
        limit: Some(10),
    }).await?;
    println!("Search returned {} results", results.data.len());

    // Check credit balance
    let balance = client.credits().balance().await?;
    println!("Balance: {} credits", balance.data.balance);

    Ok(())
}

Blocking Client

use vynco::blocking::Client;

fn main() -> Result<(), vynco::VyncoError> {
    let client = Client::builder("vc_live_your_api_key")
        .build()?;

    let balance = client.credits().balance()?;
    println!("Balance: {} credits", balance.data.balance);

    Ok(())
}

API Coverage

14 resource modules covering 52 endpoints:

Response Metadata

Every response includes header metadata for credit tracking and rate limiting:

let resp = client.companies().get("CHE-100.023.968").await?;

println!("Request ID: {:?}", resp.meta.request_id);         // X-Request-Id
println!("Credits used: {:?}", resp.meta.credits_used);      // X-Credits-Used
println!("Credits remaining: {:?}", resp.meta.credits_remaining); // X-Credits-Remaining
println!("Rate limit: {:?}", resp.meta.rate_limit_limit);    // X-Rate-Limit-Limit
println!("Rate limit remaining: {:?}", resp.meta.rate_limit_remaining); // X-RateLimit-Remaining
println!("Rate limit reset: {:?}", resp.meta.rate_limit_reset); // X-RateLimit-Reset
println!("Data source: {:?}", resp.meta.data_source);        // X-Data-Source

Configuration

use std::time::Duration;

let client = Client::builder("vc_live_your_api_key")
    .base_url("https://api.vynco.ch/api/v1")  // default
    .timeout(Duration::from_secs(60))           // default: 30s
    .max_retries(3)                             // default: 2
    .build()?;

The client automatically retries on HTTP 429 (rate limited) and 5xx (server error) with exponential backoff (500ms x 2^attempt). It respects the Retry-After header when present.

Error Handling

All API errors are mapped to typed variants:

use vynco::VyncoError;

match client.companies().get("CHE-000.000.000").await {
    Ok(resp) => println!("{}", resp.data.name),
    Err(VyncoError::Authentication(_)) => println!("Invalid API key"),
    Err(VyncoError::InsufficientCredits(_)) => println!("Top up credits"),
    Err(VyncoError::Forbidden(_)) => println!("Insufficient permissions"),
    Err(VyncoError::NotFound(body)) => println!("Not found: {}", body.detail),
    Err(VyncoError::Validation(body)) => println!("Bad request: {}", body.detail),
    Err(VyncoError::Conflict(_)) => println!("Resource conflict"),
    Err(VyncoError::RateLimit(_)) => println!("Rate limited, retry later"),
    Err(VyncoError::Server(_)) => println!("Server error"),
    Err(e) => eprintln!("Error: {e}"),
}

Error bodies follow RFC 7807 Problem Details with error_type, title, detail, status, and message fields.

Feature Flags

Minimum Supported Rust Version

Rust 1.83 or later.

License

Apache-2.0