README

What is it?

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

What is it?
Requirements
Installation
Configuration
Response
Path Parameter Interpolation
Core Functions
Endpoint Functions
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

Environment name	Constructor Argument	Type	Description
TARANA_TSP_API_HOST	$host	string	Hostname of Tarana API server
TARANA_TSP_API_TOKEN	$token	string	Authentication token issued by Tarana

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:

Name	Type	Description
status	integer	HTTP status code
statusMessage	string	HTTP status message
headers	array	HTTP response headers
body	string\|array	API response content
format	string	json or csv format

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

Name	Type	Required	Default	Description
format	string	No	csv	Specify output of JSON or CSV
operator	string	No	null	Specify operator ID

$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.

Name	Type	Required	Default	Description
operator	string	No	null	Optional operator name
days	integer	No	null	Optional report timeframe in days (default=7)
options	string	No	null	The options for prediction results
download	boolean	No	false	Set true for a download URL instead of a direct response

$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.

Name	Type	Required	Default	Description
body	array\|object	Yes		See API docs for object structures
bnLimit	integer	No	null	The limit on the number of BN predictions for each RN
options	string	No	null	Options for prediction results (cdf_graphs, path_profiles, etc.)

$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.

Name	Type	Required	Default	Description
body	array\|object	Yes		See API docs for object structures
bnLimit	integer	No	null	The limit on the number of BN predictions for each RN
options	string	No	null	Options for prediction results (cdf_graphs, path_profiles, etc.)

$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.

Name	Type	Required	Default	Description
requestId	string	Yes		The unique identifier for the prediction request
csv	boolean	No	false	Check CSV job status

$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.

Name	Type	Required	Default	Description
requestId	string	Yes		The unique identifier for the prediction request
csv	boolean	No	false	Get CSV result
format	string	No	json	body is json or csv
download	boolean	No	false	return download URL instead of returning data

$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.

Name	Type	Required	Default	Description
rnCsvFilePath	string	Yes		The CSV file with information on the RNs (limit 100)
heightCsvFilePath	string	No	null	The CSV file with information on the heights of the RNs
bnCsvFilePath	string	No	null	The CSV file with information on additional BNs to use
bnLimit	integer	No	null	The limit on the number of BN predictions for each RN
format	string	No	json	Specify the response format: 'csv' (default) or 'json'
options	string	No	null	The options for prediction results (cdf_graphs, path_profiles, etc.)
operator	string	No	null	Optional operator name
email	string	No	null	Optional email address of the requestor

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

submitMultiSectorCsv

Name	Type	Required	Default	Description
rnCsvFilePath	string	Yes		The CSV file with information on the RNs (limit 100)
heightCsvFilePath	string	No	null	The CSV file with information on the heights of the RNs
bnCsvFilePath	string	No	null	The CSV file with information on additional BNs to use
bnLimit	integer	No	null	The limit on the number of BN predictions for each RN
format	string	No	json	Specify the response format: 'csv' (default) or 'json'
options	string	No	null	The options for prediction results (cdf_graphs, path_profiles, etc.)
operator	string	No	null	Optional operator name
email	string	No	null	Optional email address of the requestor

$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.

Submit a job with submitMultiSector() or submitMultiSectorCsv()
Store the request_id from the response body
Poll getStatus() until prediction_state is completed
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().

ocolin / tarana-tsp

Maintainers

Package info

Statistics

Security