url_categories#

The following methods allow for interaction with the ZIA URL Categories API endpoints.

Methods are accessible via zia.url_categories

Guidelines for adding / updating URLs

  • The URL must use a standard URI format.

  • The URL length cannot exceed 1024 characters.

  • The URL cannot contain non-ASCII characters.

  • The domain name before the colon (:) cannot exceed 255 characters.

  • The domain name between periods (.) cannot exceed 63 characters.

class URLCategoriesAPI#

Bases: object

add_tld_category(name, tlds, **kwargs)#

Adds a new custom TLD category.

Parameters:

  • name (str) – The name of the TLD category.

  • tlds (list) – A list of TLDs in the format ‘.tld’.

  • **kwargs – Optional keyword args.

Keyword Arguments:

description (str) – Description of the category.

Returns:

The newly configured custom TLD category resource record.

Return type:

Box

Examples

Create a category for all ‘developer’ sites:

>>> zia.url_categories.add_tld_category(name='Developer Sites',
...    urls=['.dev'],
...    description="Sites that are likely run by developers.")
add_url_category(configured_name, super_category, urls, **kwargs)#

Adds a new custom URL category.

Parameters:

  • name (str) – Name of the URL category.

  • super_category (str) – The name of the parent category.

  • urls (list) – Custom URLs to add to a URL category.

  • **kwargs – Optional keyword args.

Keyword Arguments:

  • db_categorized_urls (list) – URLs entered will be covered by policies that reference the parent category, in addition to this one.

  • description (str) – Description of the category.

  • custom_category (bool) – Set to true for custom URL category. Up to 48 custom URL categories can be added per organisation.

  • ip_ranges (list) – Custom IP addpress ranges associated to a URL category. This feature must be enabled on your tenancy.

  • ip_ranges_retaining_parent_category (list) – The retaining parent custom IP addess ranges associated to a URL category.

  • keywords (list) – Custom keywords associated to a URL category.

  • keywords_retaining_parent_category (list) – Retained custom keywords from the parent URL category that are associated with a URL category.

Returns:

The newly configured custom URL category resource record.

Return type:

Box

Examples

Add a new category for beers that don’t taste good:

>>> zia.url_categories.add_url_category(name='Beer',
...    super_category='ALCOHOL_TOBACCO',
...    urls=['xxxx.com.au', 'carltondraught.com.au'],
...    description="Beers that don't taste good.")

Add a new category with IP ranges:

>>> zia.url_categories.add_url_category(name='Beer',
...    super_category='FINANCE',
...    urls=['finance.google.com'],
...    description="Google Finance.",
...    ip_ranges=['10.0.0.0/24'])
add_urls_to_category(category_id, urls)#

Adds URLS to a URL category.

Parameters:

  • category_id (str) – The unique identifier of the URL category.

  • urls (list) – Custom URLs to add to a URL category.

Returns:

The updated URL category resource record.

Return type:

Box

Examples

>>> zia.url_categories.add_urls_to_category('CUSTOM_01',
...    urls=['example.com'])
delete_category(category_id)#

Deletes the specified URL category.

Parameters:

category_id (str) – The unique identifier for the category.

Returns:

The status code for the operation.

Return type:

int

Examples

>>> zia.url_categories.delete_category('CUSTOM_01')
delete_from_category(category_id, **kwargs)#

Deletes the specified items from a URL category.

Parameters:

  • category_id (str) – The unique id for the URL category.

  • **kwargs – Optional parameters.

Keyword Arguments:

  • keywords (list) – A list of keywords that will be deleted.

  • keywords_retaining_parent_category (list) – A list of keywords retaining their parent category that will be deleted.

  • urls (list) – A list of URLs that will be deleted.

  • db_categorized_urls (list) – A list of URLs retaining their parent category that will be deleted

Returns:

The updated URL category resource record.

Return type:

Box

Examples

Delete URLs retaining parent category from a custom category:

>>> zia.url_categories.delete_from_category(
...    category_id="CUSTOM_01",
...    db_categorized_urls=['twitter.com'])

Delete URLs and URLs retaining parent category from a custom category:

>>> zia.url_categories.delete_from_category(
...    category_id="CUSTOM_01",
...    urls=['news.com', 'cnn.com'],
...    db_categorized_urls=['google.com, bing.com'])
delete_urls_from_category(category_id, urls)#

Deletes URLS from a URL category.

Parameters:

  • category_id (str) – The unique identifier of the URL category.

  • urls (list) – Custom URLs to delete from a URL category.

Returns:

The updated URL category resource record.

Return type:

Box

Examples

>>> zia.url_categories.delete_urls_from_category('CUSTOM_01',
...    urls=['example.com'])
get_category(category_id)#

Returns URL category information for the provided category.

Parameters:

category_id (str) – The unique identifier for the category (e.g. ‘MUSIC’)

Returns:

The resource record for the category.

Return type:

Box

Examples

>>> zia.url_categories.get_category('ALCOHOL_TOBACCO')
get_category_by_name(name)#
get_quota()#

Returns information on URL category quota usage.

Returns:

The URL quota statistics.

Return type:

Box

Examples

>>> zia.url_categories.get_quota()
list_categories(custom_only=False, only_counts=False)#

Returns information on URL categories.

Parameters:

  • custom_only (bool) – Returns only custom categories if True.

  • only_counts (bool) – Returns only URL and keyword counts if True.

Returns:

A list of information for all or custom URL categories.

Return type:

BoxList

Examples

List all URL categories:

>>> zia.url_categories.list_categories()

List only custom URL categories:

>>> zia.url_categories.list_categories(custom_only=True)
lookup(urls)#

Lookup the category for the provided URLs.

Parameters:

urls (list) – The list of URLs to perform a category lookup on.

Returns:

A list of URL category reports.

Return type:

BoxList

Examples

>>> zia.url_categories.lookup(['example.com', 'test.com'])
update_url_category(category_id, **kwargs)#

Updates a URL category.

Parameters:

  • category_id (str) – The unique identifier of the URL category.

  • **kwargs – Optional keyword args.

Keyword Arguments:

  • name (str) – The name of the URL category.

  • urls (list) – Custom URLs to add to a URL category.

  • db_categorized_urls (list) – URLs entered will be covered by policies that reference the parent category, in addition to this one.

  • description (str) – Description of the category.

  • ip_ranges (list) – Custom IP addpress ranges associated to a URL category. This feature must be enabled on your tenancy.

  • ip_ranges_retaining_parent_category (list) – The retaining parent custom IP addess ranges associated to a URL category.

  • keywords (list) – Custom keywords associated to a URL category.

  • keywords_retaining_parent_category (list) – Retained custom keywords from the parent URL category that are associated with a URL category.

Returns:

The updated URL category resource record.

Return type:

Box

Examples

Update the name of a category:

>>> zia.url_categories.update_url_category('CUSTOM_01',
...    name="Wines that don't taste good.")

Update the urls of a category:

>>> zia.url_categories.update_url_category('CUSTOM_01',
...    urls=['www.yellowtailwine.com'])