README

What is it?

This is a simple PHP REST client for Tarana's TSP API services.

Table of Contents

• What is it?
• Requirements
• Installation
• Configuration
  • Using Environment Variables
  • Constructor Arguments
  • Options
• Response
• Path Parameter Interpolation
• Core Functions
  • request
  • requestForm
  • requestMultipart
• Endpoint Functions
  • checkApiKey
  • findBnsWithIssues
  • predictReport
  • predictMultiSector
  • submitMultiSector
  • getStatus
  • getResult
  • predictMultiSectorCsv
  • submitMultiSectorCsv
• Async Workflow

Requirements

• PHP ^8.3
• guzzlehttp/guzzle ^7.10
• ocolin/global-type ^ 2.0

Installation

composer require ocolin/tarana-tsp

Configuration

The client can be configured using environment variables, constructor arguments, or a combination of both.

Parameters

Using environment

// Manual creation for demonstration
$_ENV['TARANA_TSP_API_HOST'] = 'https://api.tsp.taranawireless.com/';
$_ENV['TARANA_TSP_API_TOKEN'] = 'abcdefg';
$tarana = new Ocolin\TaranaTSP\TaranaTSP();

Constructor Arguments

$tarana = new Ocolin\TaranaTSP\TaranaTSP(
     host: 'https://api.tsp.taranawireless.com/',
    token: 'abcdefg'
);

Options

The client has the ability to pass Guzzle HTTP options for things such as SSL verification, HTTP timeouts, etc.

// Manual creation for demonstration
$_ENV['TARANA_TSP_API_HOST'] = 'https://api.tsp.taranawireless.com/';
$_ENV['TARANA_TSP_API_TOKEN'] = 'abcdefg';
$tarana = new Ocolin\TaranaTSP\TaranaTSP(
    options: [ 'verify' => false, 'timeout' => 20 ]
);

Response

The client will return an object with the following properties:

NOTE: When returning JSON, it will be in the form of an associative array.

Path Parameter Interpolation

Any elements or properties of a $query argument that match variable tokens in the URI endpoint path will be replaced with the values for those elements in the $query array or object. Please see some of the method functions for examples.

Core Functions

This client has 3 main functions for handling different types of data the API uses. One for JSON queries, one for form data queries, and one for multi-part queries.

Request

The request method is for endpoints that send JSON data to the API server.

$output = $tarana->request(
    endpoint: '/v0/predict/multi-sector/status/{request_id}',
      method: 'GET',
       query: [ 'request_id' => 1234 ]
);

requestForm

THis method is for API calls that require form data instead of JSON.

$output = $tarana->requestForm(
    endpoint: '/v0/find/bns/issue',
      method: 'POST',
       query: [ 'response_format' => 'csv' ],
        body: [ 'operator' => 'abcdefg' ]
);

requestMultipart

Some Tarana API calls require multi-part form submissions instead of JSON.

$output = $tarana->requestMultipart(
     endpoint: '/v0/predict/multi-sector/csv',
       method: 'POST',
    filePaths: [ 'height_csv_file.csv' => 'bn_csv_file.csv' ],
         body: [ 'operator' => 'abcdefg' ],
        query: [ 'bn_limit' => 5 ]
);

Endpoint Functions

checkApiKey

Check that API Key is valid

$output = $tarana->checkApiKey();

findBnsWithIssues

This endpoint retrieves a list of Base Nodes (BNs) for a given operator that have TCS data.

Arguments

$output = $tarana->findBnsWithIssues(
    format: 'csv',      // Output format json or csv
    operator: 'abcdefg' // Operator ID 
);

predictReport

This endpoint reports on all predictions (single and multi-sector) made over the past number of days specified (default = 7 days). An aggregated CSV file, containing the CSV portion of all the predictions made, is returned, ordered newest to oldest.

$output = $tarana->predictReport( download: true );

predictMultiSector

This endpoint predicts the path loss and speed for multiple sectors, each consisting of one Base Node (BN) and one or more Remote Nodes (RNs). It takes the MultiSector object containing information about the BNs, RNs, and optional additional BNs as input and returns an output object containing the predicted path loss, speed, and other relevant information for each sector.

$output = $tarana->predictMultiSector(
    body: {...},
    bnLimit: 10
);

submitMultiSector

This endpoint submits a job to predict the path loss and speed for multiple sectors in the background. It returns immediately with the request ID that can be used to query the status of the prediction.

$output = $tarana->submitMultiSector(
    body: {...},
    bnLimit: 10
);

getStatus

This endpoint returns the prediction status, including the progress of prediction for Base Nodes (BNs) and Remote Nodes (RNs), as well as the overall progress for all devices combined.

$output = $tarana->getStatus( requestId: 'abcdefg' );

getResult

This endpoint returns the prediction results, returning an output object containing the predicted path loss, speed, and other relevant information for each sector.

$output = $tarana->getResult( requestId: 'abcdefg' );

predictMultiSectorCsv

This endpoint predicts the path loss and speed for multiple sectors, each consisting of one Base Node (BN) and one or more Remote Nodes (RNs). It takes multiple CSV files containing information about the BNs, RNs, and optional additional BNs as input and returns an output object containing the predicted path loss, speed, and other relevant information for each sector.

$output = $tarana->predictMultiSectorCsv( rnCsvFilePath: 'file.csv' );

submitMultiSectorCsv

This endpoint submits a job to predict the path loss and speed for multiple sectors in the background. It returns immediately with the request ID that can be used to query the status of the prediction.

$output = $tarana->submitMultiSectorCsv( rnCsvFilePath: 'file.csv' );

Async Workflow

Some prediction jobs can take a long time to complete. The submit/status/result pattern allows you to submit a job and poll for completion rather than waiting for a synchronous response.

1. Submit a job with submitMultiSector() or submitMultiSectorCsv()
2. Store the request_id from the response body
3. Poll getStatus() until prediction_state is completed
4. Fetch results with getResult()

// 1. Submit
$job = $tarana->submitMultiSector( body: $data );
$requestId = $job->body['request_id'];

// 2. Poll until complete
do {
    sleep( 5 );
    $status = $tarana->getStatus( requestId: $requestId );
} while( $status->body['prediction_state'] !== 'completed' );

// 3. Fetch results
$result = $tarana->getResult( requestId: $requestId );

For CSV submissions use submitMultiSectorCsv() and pass csv: true to both getStatus() and getResult().