Reports

Reports & Data Retrieval

Comprehensive reporting endpoints for retrieving campaign performance data, analytics, and backlink information.

All endpoints require Authorization with Bearer JWT token.

Available Report Types

Keyword Reports

• Endpoint: GET /api/v1/reports/keywords/accounts/{account_id}/campaigns/{campaign_id}
• Description: Retrieve keyword ranking data and performance metrics
• Data Collection: SERP data collected every 5 days
• Best Practice: Run weekly to track ranking changes

Google Analytics Traffic Reports

• Endpoint: GET /api/v1/reports/google/analytics/traffic/accounts/{account_id}/campaigns/{campaign_id}/date_from/{date_from}/date_to/{date_to}
• Description: Get Google Analytics traffic data for campaigns
• Data Collection: Daily analytics data
• Best Practice: Run daily for traffic monitoring

Workflow Reports

• Endpoint: GET /api/v1/reports/workflows/accounts/{account_id}/campaigns/{campaign_id}/date_from/{date_from}/date_to/{date_to}
• Description: Retrieve workflow completion and task status data
• Data Collection: Real-time workflow updates
• Best Practice: Run daily for task monitoring

Backlink Reports

• Endpoint: GET /api/v1/reports/backlinks/accounts/{account_id}/campaigns/{campaign_id}
• Description: Get comprehensive backlink data for campaigns
• Data Collection: Weekly backlink scans
• Best Practice: Run weekly for backlink monitoring

Lost Backlink Reports

• Endpoint: GET /api/v1/reports/backlinks/lost/accounts/{account_id}/campaigns/{campaign_id}/date_from/{date_from}/date_to/{date_to}
• Description: Track backlinks that have been lost over time
• Data Collection: Weekly backlink scans
• Best Practice: Run weekly to identify lost opportunities

Referring Backlink Reports

• Endpoint: GET /api/v1/reports/backlinks/referring/accounts/{account_id}/campaigns/{campaign_id}/date_from/{date_from}/date_to/{date_to}
• Description: Get referring backlink data by date and count
• Data Collection: Weekly backlink scans
• Best Practice: Run weekly for referral analysis

Semify-Provisioned Backlink Reports

• Endpoint: GET /api/v1/reports/backlinks/provisioned/accounts/{account_id}/campaigns/{campaign_id}/date_from/{date_from}/date_to/{date_to}
• Description: Track backlinks provisioned by Semify services
• Data Collection: Real-time as backlinks are created
• Best Practice: Run daily for service delivery monitoring

Example Requests

Get Keyword Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/keywords/accounts/12345/campaigns/67890"

Get Google Analytics Traffic Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/google/analytics/traffic/accounts/12345/campaigns/67890/date_from/2024-01-01/date_to/2024-01-31"

Get Workflow Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/workflows/accounts/12345/campaigns/67890/date_from/2024-01-01/date_to/2024-01-31"

Get Backlink Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/backlinks/accounts/12345/campaigns/67890"

Get Lost Backlink Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/backlinks/lost/accounts/12345/campaigns/67890/date_from/2024-01-01/date_to/2024-01-31"

Get Referring Backlink Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/backlinks/referring/accounts/12345/campaigns/67890/date_from/2024-01-01/date_to/2024-01-31"

Get Semify-Provisioned Backlink Reports

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/reports/backlinks/provisioned/accounts/12345/campaigns/67890/date_from/2024-01-01/date_to/2024-01-31"

Sample Responses

Keyword Reports Response

{
  "data": [
    {
      "rank_google_organic": 5,
      "rank_google_map": 1,
      "rank_id": 12344,
      "search_total": 50,
      "histogram": [
        {
          "date": "2024-04-10T04:04:00",
          "rank_google_organic": 13
        },
        {
          "date": "2024-04-16T04:04:00",
          "rank_google_map": 1
        }
      ],
      "keyword": "home improvements maryland",
      "type": "target"
    }
  ],
  "messages": [],
  "pagination": {
    "maxRows": 0,
    "totalPages": 1,
    "offset": 0,
    "page": 1,
    "totalRecords": 0
  },
  "error": false
}

Google Analytics Traffic Response

{
  "data": [
    {
      "date": "2024-01-15",
      "sessions": 1250,
      "users": 980,
      "page_views": 3200,
      "bounce_rate": 0.45,
      "avg_session_duration": "00:02:30"
    }
  ],
  "messages": [],
  "pagination": {
    "maxRows": 0,
    "totalPages": 1,
    "offset": 0,
    "page": 1,
    "totalRecords": 0
  },
  "error": false
}

Backlink Reports Response

{
  "data": [
    {
      "url_from": "https://www.example.com",
      "url_to": "https://www.client-site.com",
      "anchor_text": "best SEO services",
      "domain_rating": 75,
      "date_discovered": "2024-01-15T10:30:00Z"
    }
  ],
  "messages": [],
  "pagination": {
    "maxRows": 0,
    "totalPages": 1,
    "offset": 0,
    "page": 1,
    "totalRecords": 0
  },
  "error": false
}

Data Collection Schedule & Best Practices

SERP Data Collection

• Frequency: Every 5 days
• Recommended Pull Frequency: Weekly (to capture all updates)
• Best Practice: Run keyword reports every Monday to get the latest 5-day cycle data

Analytics Data Collection

• Frequency: Daily
• Recommended Pull Frequency: Daily
• Best Practice: Run traffic reports daily for real-time monitoring

Backlink Data Collection

• Frequency: Weekly scans
• Recommended Pull Frequency: Weekly
• Best Practice: Run backlink reports weekly to track link building progress

Workflow Data Collection

• Frequency: Real-time updates
• Recommended Pull Frequency: Daily
• Best Practice: Run workflow reports daily to monitor task completion

Report Scheduling Recommendations

Daily Reports (High Priority)

• Google Analytics Traffic Reports
• Workflow Reports
• Semify-Provisioned Backlink Reports

Weekly Reports (Medium Priority)

• Keyword Reports (after 5-day SERP collection)
• Backlink Reports
• Lost Backlink Reports
• Referring Backlink Reports

Monthly Reports (Low Priority)

• Aggregate performance summaries
• Trend analysis reports
• Client reporting packages

Important Notes

• Date Format: Use YYYY-MM-DD format for date parameters
• Rate Limiting: Be mindful of API rate limits when scheduling frequent pulls
• Data Freshness: SERP data is collected every 5 days, so keyword reports may not show daily changes
• Error Handling: Check response messages and error flags for proper error handling

Recommendations

• Schedule Regular Pulls: Set up automated daily/weekly pulls based on data collection frequency
• Use Incremental Pulls: Use date ranges to pull only new data since last update
• Store Last Retrieved Data: Keep track of last pull timestamps to avoid duplicate data
• Implement Error Handling: Handle API errors gracefully and retry failed requests
• Monitor Data Quality: Validate report data for completeness and accuracy
• Optimize Query Ranges: Use appropriate date ranges to minimize payload sizes
• Cache Results: Store frequently accessed reports to reduce API calls