SuggestGrid PHP Client

We will walk through how to get started with SuggestGrid PHP Client in three steps:

1. Configuration

2. Post actions

3. Get recommendations

Getting Started

In this guide we will demonstrate how to display personalized recommendations on an existing PHP Framework project.

We have a movie catalog PHP Framework application, SuggestGridMovies, similar to IMDb. For logged in users we want to display movies that similar people viewed on movie pages. Let's implement this feature in five minutes with SuggestGrid!

1. Configuration

We are beginning the development by adding the client as a dependency.

SuggestGrid PHP client is available in packagist at packagist.org/packages/suggestgrid/suggestgrid.

In order to use the client with composer add the following to your composer.json file:

"require": {
    "suggestgrid/suggestgrid": "*"
}

Once you sign up for SuggestGrid, you'll see your SUGGESTGRID_URL parameter on the dashboard in the format below:

http://{user}:{pass}@{region}.suggestgrid.space/{app-uuid}

You can authenticate your application using SUGGESTGRID_URL environment variable like the example below:

$suggestGridClient = new SuggestGridLib\SuggestGridClient(getenv('SUGGESTGRID_URL'));

Every recommendation logic needs to belong to a type. For this demonstration we can create an implicit type named as views. This could be done either from the dashboard or with a snippet like this:

$type_name = 'views';
$suggestGridTypeController = $suggestGridClient->getType();

try {
    $suggestGridTypeController->getType($type_name);    
} catch (SuggestGridLib\APIException $e) {
    $suggestGridTypeController->createType($type_name);
}

2. Post actions

Once the type exists, let's start posting actions. We should invoke SuggestGrid client's SuggestGridLib\Controllers\ActionController::postAction( $action ) when an user views an item in our application.

We can do this by putting the snippet below on the relevant point:

$suggestGridActionController = $suggestGridClient->getAction();

$action = new SuggestGridLib\Models\Action($type_name, '1', '2');
$suggestGridActionController->postAction($action);

The more actions SuggestGrid gets, more relevant and diverse its responses are.

3. Get recommendations

Finally, let's show "movies similar users viewed" on movie pages.

SuggestGrid needs recommendation models for returning recommendations. Model generation is scheduled in every 24 hours. In addition, instant model generations can be triggered on the dashboard.

Once the first model generated for 'views' type, recommendations could be get using a snippet like the following:

$suggestGridRecommendationController = $suggestGridClient->getRecommendation();

$recommendedItemsResponse = $suggestGridRecommendationController->getRecommendedItems(array('type' => $type_name, 'user_id' => 1));
$recommendedItems = $recommendedItemsResponse->items;

Type Methods

Type methods are used for creating, getting, and deleting types. Refer to types for an overview.

Creates a Type

SuggestGridLib\Controllers\TypeController::createType( $type, $settings = null )

Creates a new type.

Creating an explicit type:

$suggestGridTypeController = $suggestGridClient->getType();

$suggestGridTypeController->createType($type);

or:

$suggestGridTypeController = $suggestGridClient->getType();

$suggestGridTypeController->createType($type, array('rating' => 'explicit'));

Creating an implicit type:

$suggestGridTypeController = $suggestGridClient->getType();

$suggestGridTypeController->createType($type, array('rating' => 'implicit')

Parameters

URI/Query Parameters

Body Parameters

TypeRequestBody (object)

Gets Properties of a Type

SuggestGridLib\Controllers\TypeController::getType( $type )

Returns the options of a type. The response rating parameter.

$suggestGridTypeController = $suggestGridClient->getType();

$suggestGridTypeController->getType($type)

Throws a SuggestGridLib\APIException in case the type is not found.

Parameters

URI/Query Parameters

Deletes a Type

SuggestGridLib\Controllers\TypeController::deleteType( $type )

Warning: Deletes the type with all of its actions and its recommendation model.

$suggestGridTypeController = $suggestGridClient->getType();

$suggestGridTypeController->deleteType($type);

Parameters

URI/Query Parameters

Gets All Types

SuggestGridLib\Controllers\TypeController::getAllTypes()

Returns all type names in an array named types.

$suggestGridTypeController = $suggestGridClient->getType();

$types = $suggestGridTypeController->getAllTypes()->types;

Deletes All Types

SuggestGridLib\Controllers\TypeController::deleteAllTypes()

Deletes ALL the types and ALL the actions.

$suggestGridTypeController = $suggestGridClient->getType();

$suggestGridTypeController->deleteAllTypes();

Action Methods

Action methods are for creating, getting, and deleting actions. Refer to actions for an overview.

Posts an Action

SuggestGridLib\Controllers\ActionController::postAction( $action )

Posts an action to the given type in the body. The body must have user id, item id and type. Rating is required for actions sent to an explicit type.

If the type with name $type is implicit an action can be posted as the following:

$suggestGridActionController = $suggestGridClient->getAction();

$action = new SuggestGridLib\Models\Action($type, '1', '2');
$suggestGridActionController->postAction($action);

Otherwise, if the type is explicit, rating parameter must also be posted:

$suggestGridActionController = $suggestGridClient->getAction();

$action = new SuggestGridLib\Models\Action($type, '1', '2', 5);
$suggestGridActionController->postAction($action);

Note that type parameter with a string value must be provided. user_id and item_id paramters must be provided as well and their values can be integers or strings.

Parameters

Body Parameters

Action (object)

Posts Actions

SuggestGridLib\Controllers\ActionController::postBulkActions( $actions )

Posts bulk actions to SuggestGrid. The recommended method for posting multiple actions at once.

For posting bulk actions an array of actions must be created first. Below is an example of posting bulk implicit actions:

$suggestGridActionController = $suggestGridClient->getAction();

$actions = array();
array_push($actions, new SuggestGridLib\Models\Action($type, '1', '1'));
array_push($actions, new SuggestGridLib\Models\Action($type, '2', '2'));

$suggestGridActionController->postBulkActions($actions);

Similarly, explicit actions could be posted in bulk as below:

$suggestGridActionController = $suggestGridClient->getAction();

$actions = array();
array_push($actions, new SuggestGridLib\Models\Action($type, '1', '1', 5));
array_push($actions, new SuggestGridLib\Models\Action($type, '2', '2', 5));

$suggestGridActionController->postBulkActions($actions);

Parameters

Gets Actions

SuggestGridLib\Controllers\ActionController::getActions( $type = null, $userId = null, $itemId = null, $olderThan = null, $size = null, $from = null )

Get actions. Defaut responses will be paged by 10 actios each. Type, user id, item id, or older than parameters could be provided. The intersection of the provided parameters will be returned.

Get all actions:

$suggestGridActionController = $suggestGridClient->getAction();

$alllActionsCount = $suggestGridActionController->getActions()->totalCount;

Get all actions of a type:

$suggestGridActionController = $suggestGridClient->getAction();

$typeActionsCount = $suggestGridActionController->getActions($type)->totalCount;

Get all actions of a user:

$suggestGridActionController = $suggestGridClient->getAction();

$userActionsCount = $suggestGridActionController->getActions(null, $userId)->totalCount;

You can include any of type, userId, itemId, and olderThan query parameters and SuggestGrid would return the actions satisfying all the query parameters: olderThan value could be a ISO 8601 duration, or a Unix time number.

Parameters

URI/Query Parameters

Delete Actions

SuggestGridLib\Controllers\ActionController::deleteActions( $type = null, $userId = null, $itemId = null, $olderThan = null )

Warning: Please use get actions with the exact parameters first to inspect the actions to be deleted.

• Type must be provided.
• If user id is provided, all actions of the user will be deleted.
• If item id is provided, all actions on the item will be deleted.
• If older than is provided, all actions older than the timestamp or the duration will be deleted.
• If a number of these parameters are provided, the intersection of these parameters will be deleted.
• In addition to a type, at least one of these parameters must be provided. In order to delete all the actions of a type, delete the type.

Type and at least one more parameter and at least one more parameter must be provided for all delete actions queries.

Delete a user's actions:

$suggestGridActionController = $suggestGridClient->getAction();

$suggestGridActionController->deleteActions($type, $userId);

Delete an item's actions:

$suggestGridActionController = $suggestGridClient->getAction();

$suggestGridActionController->deleteActions($type, null, $itemId);

Delete old actions:

olderThan value could be a ISO 8601 duration in the form of PnDTnHnM, or a Unix time number.

Example durations:

• P365D: Approximately a year.
• P30D: Approximately a month.
• P1DT12H: One and a half days.
• P1D: A day (where a day is 24 hours or 86400 seconds).
• PT12H: 10 hours (where an hour is 3600 seconds).
• PT1M: 1 minute.

Delete actions older than a month:

$suggestGridActionController = $suggestGridClient->getAction();

$suggestGridActionController->deleteActions($type, null, null, 'P30D');

Delete actions by query:

You can include any of userId, itemId, and olderThan parameters to the delete query and SuggestGrid would delete the intersection of the given queries accordingly.

For example, if all of userId, itemId, and olderThan are provided, SuggestGrid would delete the actions of the given user on the given item older than the given time or duration.

$suggestGridActionController = $suggestGridClient->getAction();

$suggestGridActionController->deleteActions($type, '1', '30', '891628467');

It's highly recommended to first get the actions with the same parameters before deleting actions.

Parameters

URI/Query Parameters

Metadata Methods

Metadata methods are for creating, getting, and deleting user, and item metadata. Refer to metadata for an overview.

Posts a User

SuggestGridLib\Controllers\MetadataController::postUser( $user )

Posts a user metadata. Note that this operation completely overrides previous metadata for the id, if it exists.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$suggestGridMetadataController->postUser( array('id' => 1, 'name' => 'Anna') );

Parameters

Body Parameters

Metadata (object)

Posts Users

SuggestGridLib\Controllers\MetadataController::postBulkUsers( $users )

Posts user metadata in bulk. Note that this operation completely overrides metadata with the same ids, if they exist.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$users = array();
array_push($users, array('id' => 1, 'name' => 'Anna'));
array_push($users, array('id' => 2, 'name' => 'John'));

$suggestGridMetadataController->postBulkUsers($users);

Parameters

Gets A User

SuggestGridLib\Controllers\MetadataController::getUser( $userId )

Returns a user metadata if it exists.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$user42 = $suggestGridMetadataController->getUser('42');

Parameters

URI/Query Parameters

Gets Users

SuggestGridLib\Controllers\MetadataController::getUsers( $size = null, $from = null )

Get items and total count of items. Page and per-page parameters could be set.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$usersCount = $suggestGridMetadataController->getUsers()->totalCount;

Parameters

URI/Query Parameters

Deletes a User

SuggestGridLib\Controllers\MetadataController::deleteUser( $userId )

Deletes a user metadata with the given user id.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$suggestGridMetadataController->deleteUser(1);

Parameters

URI/Query Parameters

Deletes All Users

SuggestGridLib\Controllers\MetadataController::deleteAllUsers()

Warning: Deletes all user metadata from SuggestGrid.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$suggestGridMetadataController->deleteAllUsers();

Posts An Item

SuggestGridLib\Controllers\MetadataController::postItem( $item )

Posts an item metadata. Note that this operation completely overrides previous metadata for the id, if it exists.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$suggestGridMetadataController->postItem( array('id' => 1, 'price' => 99) );

Parameters

Body Parameters

Metadata (object)

Posts Items

SuggestGridLib\Controllers\MetadataController::postBulkItems( $items )

Posts item metadata in bulk. Note that this operation completely overrides metadata with the same ids, if they exist.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$items = array();
array_push($items, array('id' => 1, 'price' => 99));
array_push($items, array('id' => 2, 'price' => 399));

$suggestGridMetadataController->postBulkItems($items);

Parameters

Gets An Item

SuggestGridLib\Controllers\MetadataController::getItem( $itemId )

Returns an item metadata if it exists.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$item42 = $suggestGridMetadataController->getItem('42');

Parameters

URI/Query Parameters

Gets Items

SuggestGridLib\Controllers\MetadataController::getItems( $size = null, $from = null )

Gets items and total count of items. Page and per-page parameters could be set.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$itemsCount = $suggestGridMetadataController->getItems()->totalCount;

Parameters

URI/Query Parameters

Delete An Item

SuggestGridLib\Controllers\MetadataController::deleteItem( $itemId )

Deletes an item metadata with the given item id.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$suggestGridMetadataController->deleteItem(1);

Parameters

URI/Query Parameters

Deletes All Items

SuggestGridLib\Controllers\MetadataController::deleteAllItems()

Warning: Deletes all item metadata from SuggestGrid.

$suggestGridMetadataController = $suggestGridClient->getMetadata();

$suggestGridMetadataController->deleteAllItems();

Recommendation Methods

Recommendation methods are for getting recommended items for users, or recommended users for items. Refer to recommendations for an overview.

Gets Recommended Users

SuggestGridLib\Controllers\RecommendationController::getRecommendedUsers( $query )

Returns recommended users for the query.

Below is a basic recommended users request:

$suggestGridRecommendationController = $suggestGridClient->getRecommendation();

$itemId = 1;

$recommendedUsersResponse = $suggestGridRecommendationController->getRecommendedUsers(array('item_id' => $itemId));
$recommendedUsers = $recommendedUsersResponse->users;

Note that when no type parameter is provided, all types are used for recommendation. Therefore, it's highly suggested to provide the type parameter.

$type = 'views';
$itemId = 1;

$suggestGridRecommendationController->getRecommendedUsers(array('type' => $type, 'user_id' => $userId));

User recommendations accept a number of parameters. They are type, types, item_id, item_ids, except, similar_user_id, similar_user_ids, size, filter, and fields. For detailed information about them, read recommendations documentation.

Below is a more complex recommended items query:

$type = 'views';
$itemId = 1;
$except = 1;
$similarUserId = 42;
$size = 5;
$filter = array('equal' => array( 'field' => 'parameter'));
$fields = array('field');

$recommendedUsersResponse = $suggestGridRecommendationController->getRecommendedUsers(array('type' => $type, 'item_id' => $itemId, 'size' => $size, 'filter' => $filter,  'fields' => $fields, 'simiar_user_id' => $similarUserId, 'except' => $except));
$recommendedUsers = $recommendedUsersResponse->users;

Parameters

Body Parameters

GetRecommendedUsersBody (object)

Gets Recommended Items

SuggestGridLib\Controllers\RecommendationController::getRecommendedItems( $query )

Returns recommended items for the query.

Below is a basic recommended items request:

$suggestGridRecommendationController = $suggestGridClient->getRecommendation();

$userId = 1;

$recommendedItemsResponse = $suggestGridRecommendationController->getRecommendedItems(array('user_id' => $userId));
$recommendedItems = $recommendedItemsResponse->items;

Note that when no type parameter is provided, all types are used for recommendation. Therefore, it's highly suggested to provide the type parameter.

$type = 'views';
$userId = 1;

$suggestGridRecommendationController->getRecommendedItems(array('type' => $type, 'user_id' => $userId));

Item recommendations accept a number of parameters. They are type, types, user_id, user_ids, except, similar_item_id, similar_item_ids, size, filter, and fields. For detailed information about them, read recommendations documentation.

Below is a more complex recommended items query:

$type = 'views';
$userId = 1;
$except = 1;
$similarItemId = 42;
$size = 5;
$filter = array('equal' => array( 'field' => 'parameter'));
$fields = array('field');

$recommendedItemsResponse = $suggestGridRecommendationController->getRecommendedItems(array('type' => $type, 'user_id' => $userId, 'size' => $size, 'filter' => $filter,  'fields' => $fields, 'simiar_item_id' => $similarItemId, 'except' => $except));
$recommendedItems = $recommendedItemsResponse->items;

Parameters

Body Parameters

GetRecommendedItemsBody (object)

Similarity Methods

Similarity methods are for getting similar items, or similar users. Refer to similarities for an overview.

Gets Similar Users

SuggestGridLib\Controllers\RecommendationController::getSimilarUsers( $query )

Returns similar users for the query.

Below is a basic similar users request:

$suggestGridSimilarityController = $suggestGridClient->getSimilarity();

$userId = 1;

$similarUsersResponse = $suggestGridSimilarityController->getSimilarUsers(array('user_id' => $userId));
$similarUsers = $similarUsersResponse->Users;

Note that when no type parameter is provided, all types are used for similarities. Therefore, it's highly suggested to provide the type parameter.

$type = 'views';
$userId = 1;

$suggestGridSimilarityController->getSimilarUsers(array('type' => $type, 'user_id' => $userId));

User similarities accept a number of parameters. They are type, types, user_id, user_ids, except, size, filter, and fields. For detailed information about them, read similarities documentation.

Below is a more complex similar users query:

$type = 'views';
$userId = 1;
$except = 12;
$size = 5;
$filter = array('equal' => array( 'field' => 'parameter'));
$fields = array('field');

$similarUsersResponse = $suggestGridSimilarityController->getSimilarUsers(array('type' => $type, 'user_id' => $userId, 'size' => $size, 'filter' => $filter,  'fields' => $fields, 'except' => $except));
$similarUsers = $similarUsersResponse->Users;

Parameters

Body Parameters

GetSimilarUsersBody (object)

Gets Similar Items

SuggestGridLib\Controllers\SimilarityController::getSimilarItems ( $query )

Returns similar items for the query.

Below is a basic similar items request:

$suggestGridSimilarityController = $suggestGridClient->getSimilarity();

$itemId = 1;

$similarItemsResponse = $suggestGridSimilarityController->getSimilarItems(array('item_id' => $itemId));
$similarItems = $similarItemsResponse->items;

Note that when no type parameter is provided, all types are used for similarities. Therefore, it's highly suggested to provide the type parameter.

$type = 'views';
$itemId = 1;

$suggestGridSimilarityController->getSimilarItems(array('type' => $type, 'item_id' => $itemId));

Item similarities accept a number of parameters. They are type, types, item_id, item_ids, except, size, filter, and fields. For detailed information about them, read similarities documentation.

Below is a more complex similar items query:

$type = 'views';
$itemId = 1;
$except = 12;
$size = 5;
$filter = array('equal' => array( 'field' => 'parameter'));
$fields = array('field');

$similarItemsResponse = $suggestGridSimilarityController->getSimilarItems(array('type' => $type, 'item_id' => $itemId, 'size' => $size, 'filter' => $filter,  'fields' => $fields, 'except' => $except));
$similarItems = $similarItemsResponse->items;

Parameters

Body Parameters

GetSimilarItemsBody (object)