data-for-seo

data-for-seo is a Rust client library for the DataForSEO API v3. It covers every API domain of v3 with typed request/response models, while staying resilient to API changes (unknown fields and item types never break deserialization).

[dependencies]
data-for-seo = "0.3"

Quick start

use data_for_seo::{DataForSeoClient, BacklinksApiSummaryPost};

#[tokio::main]
async fn main() -> Result<(), data_for_seo::error::DataForSeoError> {
    let client = DataForSeoClient::new("login", "password");

    let response = client
        .backlinks()
        .summary(vec![BacklinksApiSummaryPost::new("https://example.com/")])
        .await?;

    for result in response.results() {
        println!("backlinks: {:?}", result.backlinks);
    }
    Ok(())
}

The client is organized by API domain, mirroring the DataForSEO documentation:

client.serp().google()            client.dataforseo_labs().google()
client.serp().bing()              client.dataforseo_labs().amazon()
client.serp().youtube()           client.dataforseo_labs().apple()
client.keywords_data().google_ads()
client.keywords_data().bing()     client.merchant().amazon()
client.on_page()                  client.merchant().google()
client.backlinks()                client.app_data().google()
client.domain_analytics().technologies()
client.content_analysis()         client.business_data().google()
client.content_generation()       client.ai_optimization().chat_gpt()

Task-based endpoints

Many endpoints follow DataForSEO's task flow (task_post → tasks_ready → task_get):

use data_for_seo::{DataForSeoClient, SerpApiGoogleOrganicTaskPostRequest};

async fn example(client: &DataForSeoClient) -> Result<(), data_for_seo::error::DataForSeoError> {
    let mut request = SerpApiGoogleOrganicTaskPostRequest::new("ja".to_string(), 2392);
    request.keyword = "seo".to_string();

    let posted = client.serp().google().organic_task_post(vec![request]).await?;
    let task_id = &posted.tasks()[0].id;

    // ... poll tasks_ready, then:
    let result = client.serp().google().organic_task_get_advanced(task_id).await?;
    for page in result.results() {
        for item in page.items() {
            println!("{:?}", item);
        }
    }
    Ok(())
}

Response helpers

Every call returns DataForSeoApiResponse<T> (= Result<DataForSeoApiResponseData<T>, DataForSeoError>). The response data exposes:

• response.tasks() — all tasks as a slice (never panics on null)
• response.results() / response.into_results() — iterate every result of every task
• response.first_result() — first result across all tasks
• task.results(), task.is_success(), task.task_status() — per-task access

Credentials

You need a DataForSEO account (affiliate link) to get API credentials. Pass your API login and password directly (DataForSeoClient::new), or read them from the DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD environment variables:

use data_for_seo::DataForSeoClient;

let client = DataForSeoClient::from_env()?; // DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD

Sandbox

DataForSEO's sandbox is free and returns mock data:

use data_for_seo::DataForSeoClient;
let client = DataForSeoClient::new("login", "password").sandbox();

Error handling

DataForSeoError implements std::error::Error and distinguishes:

• Api — the API returned an error envelope (status_code, status_message, see error codes)
• Http — a non-JSON HTTP failure
• System — transport or deserialization failure

Supported API domains (all v3 domains)

A few endpoints whose response schema is not documented return serde_json::Value so the raw data is still accessible.

Examples

Runnable examples for the most common workflows live in examples/:

• quick_start.rs — minimal setup: live call + posting a task
• serp_live.rs — check Google rankings with one live request, matching SERP item types
• serp_task_flow.rs — the full task flow: post → poll tasks_ready → fetch results
• keywords_search_volume.rs — Google Ads search volume for a keyword list
• backlinks_overview.rs — backlink profile: summary, referring domains, newest links
• labs_keyword_research.rs — keyword ideas and related keywords with metrics
• onpage_audit.rs — crawl a site and read OnPage scores per page

DATAFORSEO_LOGIN=... DATAFORSEO_PASSWORD=... cargo run --example serp_live

Testing

cargo test                 # offline deserialization tests (no credentials needed)
cargo test -- --ignored    # live API tests; requires .env with ID and PASSWORD

License

MIT