Change language settings to use Topvisor in your preferred language. You can select and set a preferred language later in the Account settings. Change language settings to use Topvisor in your preferred language. ru Русский Apply

Filters (filters and id)

Filters are used to receive, edit or delete objects.
Id is used to receive, edit or delete an object.

Filters parameter structure

filters is an array of fieldFilter filter objects.
A filter has the following properties:

  • fieldFilter.name - field name
  • fieldFilter.operator - comparison operator
  • fieldFilter.values - array of filter values

fieldFilter.values is always an array, including the comparison operators with a single fieldFilter value (e.g. EQUALS)

{"filters":[{"name": /* Field name (string) */", "operator": /* Comparison operator (string) */", "values":[ /* Filter values */ ]}, /*...*/]}

Filter values

fieldFilter.values can contain integers, strings and field values.

To add a field as a filter value, use the following format: "Field:{Field_name}".
Do not use the BETWEEN, REGEXP, and NOT_REGEXP operators when comparing a field to the other fields.

Available comparison operators

Operator Comparison description Function
EQUALS equal to the specified value =
NOT_EQUALS not equal to the specified value !=
IN exists among the specified values IN()
NOT_IN doesn't exist among the specified values NOT IN()
GREATER_THAN greater than the specified value >
GREATER_THAN_EQUALS greater than or equal to the specified value >=
LESS_THAN less than the specified value <
LESS_THAN_EQUALS less than or equal to the specified value <=
BETWEEN between values 1 and 2. You can add a series of intervals:

values = [10,20,50,100]; // 10..20 or 50..100
BETWEEN
STARTS_WITH starts with the specified value LIKE '%_'
CONTAINS contains a substring with the specified value LIKE '%_%'
DOES_NOT_CONTAIN doesn't contain a substring with the specified value NOT LIKE '%_%'
REGEXP regular expression matching the specified value REGEXP()
NOT_REGEXP regular expression excluding the specified value NOT REGEXP()
IS_NULL field set to null IS NULL
IS_NOT_NULL field isn't set to null IS NOT null

id parameter

Please note that an id parameter passed in the request is added to the filters as:

{"name":"id", "operator":"EQUALS", "values":["{Parameter_value_id}"]}

So, id parameter is a short form of the filter by id.
We recommend using this parameter to edit a single object.

Examples

To get tag numbers in the example, we use the fields parameter.

In the example below, we'll get a list of keywords added to NN project with the tag 2 or 3.

Request


POST /v2/json/get/keywords_2/keywords/

{"project_id": /* project id (int) */,"fields":["id","name","tags"]}

Result


			{"result":[{"id":"80764821","name":"test keyword 1","tags":"2"},{"id":"80764822","name":"test keyword 2","tags":"2"},{"id":"80764823","name":"test keyword 3","tags":"3"},{"id":"80764824","name":"test keyword 4","tags":"4"},{"id":"80764825","name":"test keyword 5","tags":"5"}]}
			

Request


POST /v2/json/get/keywords_2/keywords/

{"project_id": /* project id (int) */,"fields":["id","name","tags"],"filters":[{"name":"tags","operator":"IN","values":[2,3]}]}

Result


			{"result":[{"id":"80764821","name":"test keyword 1","tags":"2"},{"id":"80764822","name":"test keyword 2","tags":"2"},{"id":"80764823","name":"test keyword 3","tags":"3"}]}
			

Request


POST /v2/json/get/keywords_2/keywords/

{"project_id": /* project id (int) */,"fields":["id","name","tags"],"id":80764821}

Result


			{"result":[{"id":"80764821","name":"test keyword 1","tags":"2"}]}
			

SDK example

In the example below, we'll get a list of keywords added to the NN project with the tags 2 or 3.

	<?php

	$projectId = '%NN%'; // ID of your project

	$TVSession = new TVSession();

	$selectorKeywords = new TVPen($TVSession, 'get', 'keywords_2', 'keywords');
	$selectorKeywords->setFields(['id', 'name', 'tags']);
	$selectorKeywords->setData(['project_id' => $project_id]);
	$selectorKeywords->setFilters([
	TVFields::genFilterData('tags', 'IN', [2, 3])
	]);

	$page = $selectorKeywords->exec();
	if(is_null($page->getResult())) return var_dump($page->getErrors());

	// $page - array of keywords
	foreach($page->getResult() as $resultItem){
	var_dump($resultItem);
	}