Skip to main content

Data Source

The Imagga API connector enables you to ingest image analysis results — including tags, categories, colors, faces, and moderation signals — from any Imagga API endpoint. Follow the instructions below to create a new data flow that ingests data from an Imagga API source in Nexla.
imagga_api.png

Imagga API

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Imagga API connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Imagga API, and click Next; or, create a new Imagga API credential for use in this flow.

  3. In Nexla, Imagga API data sources can be created using pre-built endpoint templates, which expedite source setup for common Imagga API endpoints. Each template is designed specifically for the corresponding Imagga API endpoint, making data source setup easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Imagga API sources can also be configured manually, allowing you to ingest data from Imagga API endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Imagga API endpoints. Each template is designed specifically for the corresponding Imagga API endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    List Categorizers

    Returns a list of available image categorizers that can be used for image classification. Use this endpoint to discover the categorizer IDs available on your Imagga account before running categorization workflows.

    • Sends a GET request to https://api.imagga.com/v2/categorizers and returns all available categorizers.
    • Response data is nested under $.result.categorizers[*]; each element describes a single categorizer including its ID, title, and supported labels.

    Categorizer IDs returned by this endpoint (e.g., personal_photos) are used as path parameters in the Categorize Photos endpoint. Run this endpoint first to identify the correct categorizer for your use case.

    Get Image Croppings

    Detects and returns suggested smart crop regions for a provided image URL. Use this endpoint to generate optimal crop coordinates for thumbnail generation or responsive image pipelines.

    The image URL must be publicly accessible. Imagga will fetch the image directly from the provided URL when processing the request.

    Get Image Colors

    Extracts and returns the dominant colors and color distribution from a provided image URL. Use this endpoint to power color-based search, product classification, or brand compliance workflows.

    • Sends a GET request to https://api.imagga.com/v2/colors?image_url=<url> with the target image URL as a query parameter.
    • Response data is nested under $.result.colors[*]; results include foreground and background dominant color data with percentage coverage and HTML hex values.

    The image URL must be publicly accessible. Color extraction works best on images with clear subject separation from the background.

    Detect Faces

    Detects and returns information about faces found in a provided image URL, including bounding box coordinates and confidence scores. Use this endpoint to count faces, crop portraits, or gate downstream face recognition workflows.

    Face detection accuracy may vary with image quality, lighting, and occlusion. Review confidence scores in the response to filter low-quality detections before downstream processing.

    Extract Text

    Extracts and returns text recognized in a provided image URL using optical character recognition (OCR). Use this endpoint to digitize text from images, receipts, signage, or scanned documents.

    • Sends a GET request to https://api.imagga.com/v2/text?image_url=<url> with the target image URL as a query parameter.
    • Response data is nested under $.result.text[*]; each element contains a recognized text region with coordinates and the extracted string.

    OCR results are most accurate on high-resolution images with clear, well-contrasted text. Low-resolution or skewed text may produce incomplete extractions.

    Get API Usage

    Returns the current API usage statistics and remaining quota for the authenticated Imagga account. Use this endpoint to monitor consumption and avoid quota overruns in production data flows.

    • Sends a GET request to https://api.imagga.com/v2/usage and returns usage statistics for the current billing period.
    • Response data is returned at $.result as a single object containing call counts, quota limits, and reset dates.

    Schedule this endpoint to run periodically to track API consumption trends. Alert thresholds can be applied in downstream Nexla flows to notify when quota is approaching its limit.

    Detect Barcodes

    Detects and returns barcode and QR code information from a provided image URL. Use this endpoint to extract product identifiers, URLs, or inventory codes from product images.

    • Sends a GET request to https://api.imagga.com/v2/barcodes?image_url=<url> with the target image URL as a query parameter.
    • Response data is nested under $.result.barcodes[*]; each element contains the barcode type, decoded value, and bounding box coordinates.

    The image URL must be publicly accessible. Multiple barcodes within a single image are all returned in the response array.

    Categorize Photos

    Classifies a provided image URL into predefined categories and returns matching categories with confidence scores. Use this endpoint to automatically organize images by subject type using a named categorizer.

    • Sends a GET request to https://api.imagga.com/v2/categories/{'{categorizerId}'}?image_url=<url> with the categorizer ID in the path and the image URL as a query parameter.
    • Response data is nested under $.result.categories[*]. Configure the following parameters: Categorizer ID — the ID of the Imagga categorizer to use (e.g., personal_photos). Use the List Categorizers endpoint to discover available IDs.

    Each categorizer is trained for a specific set of image categories. Verify that the selected categorizer is appropriate for your image content before building production flows.

    Retrieve Descriptive Tags for an Image

    Retrieves automatically generated descriptive tags for an image — the flagship Imagga feature. Use this endpoint to enrich image metadata with semantic tags for search, filtering, or content moderation.

    This is Imagga's most commonly used endpoint. Tags are returned in descending confidence order. Apply a minimum confidence threshold in downstream Nexla transformations to filter low-confidence tags.

    Detect and Localise Objects within an Image

    Detects and localizes specific objects within an image, returning bounding boxes for each detected object. Use this endpoint to identify and locate products, people, or other objects within images for spatial analysis.

    Object localization is available on Imagga's paid plans. Verify that your Imagga subscription includes this feature before building flows that depend on it.

    Compare Face Images and Return Similarity Score

    Compares two face images and returns a similarity score. Use this endpoint to verify identity matches or detect duplicate face images in a dataset.

    • Sends a GET request to https://api.imagga.com/v2/faces/similarity with both image URLs (or upload IDs) provided as query parameters.
    • Response data is returned at $.result as a single object containing the similarity score.

    Both image sources must contain a detectable face for the comparison to succeed. Ensure input images are pre-validated with the Detect Faces endpoint if face presence is not guaranteed.

    Find Visually Similar Images (Visual Search)

    Finds visually similar images within a pre-built index. Use this endpoint to implement visual product search or content deduplication workflows.

    • Sends a GET request to https://api.imagga.com/v2/similar-images/{'{imageId}'} where the path parameter is the image ID or a URL-encoded image URL.
    • Response data is nested under $.result.similar_images[*]. Configure the following parameters: Image ID or URL — the identifier of the query image within the visual search index.

    A pre-built visual search index must exist on your Imagga account before using this endpoint. Refer to the Imagga documentation for instructions on creating and populating an index.

    Get Structured Tags (v3)

    Retrieves structured semantic tags for an image grouped by objects, scene, mood, colors, and extended categories using the Imagga v3 API. Use this endpoint for richer, more organized tag data compared to the standard v2 tags endpoint.

    The v3 tags endpoint is available on specific Imagga plans. Verify that your subscription includes v3 API access before using this endpoint in production flows.

    Get Semantic Croppings (v3)

    Analyzes an image and returns structured semantic crop boxes with subject metadata, bounding coordinates, and reasoning using the Imagga v3 API. Use this endpoint for advanced, semantically-aware image cropping workflows.

    The v3 croppings endpoint is available on specific Imagga plans. Verify that your subscription includes v3 API access before using this endpoint in production flows.

    Get Async Job Ticket

    Retrieves the status and results of an asynchronous Imagga job (e.g., face groupings or index training) using its ticket ID. Use this endpoint to poll for completion of long-running Imagga operations initiated in prior flow steps.

    • Sends a GET request to https://api.imagga.com/v2/tickets/{'{ticketId}'} with the ticket ID in the path.
    • Response data is returned at $.result as a single object containing job status and, when complete, the job results. Configure the following parameters: Ticket ID — the ID of the async job ticket to check.

    Poll this endpoint periodically until the job status indicates completion. Nexla date/time macros and scheduled flow runs can be used to implement a polling pattern.

    Search Face Recognition Index

    Queries a face recognition index to find matching people for a given face ID, with support for offset and count pagination. Use this endpoint to identify individuals within a face recognition index built from your image dataset.

    • Sends a GET request to https://api.imagga.com/v2/faces/recognition/{'{indexId}'} with the recognition index ID in the path and a face ID as a query parameter.
    • Response data is nested under $.result.people[*]. Configure the following parameters: Face Recognition Index ID — the ID of the face recognition index to search.

    A face recognition index must be created and populated before this endpoint can be used. Refer to the Imagga documentation for instructions on building face recognition indexes.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Imagga API sources can also be configured to ingest data from any valid Imagga API endpoint. The Imagga REST API is organized around standard HTTP methods and returns results in JSON format. Common use cases include ingesting auto-generated image tags, categories, color palettes, face detection results, and content moderation signals for downstream enrichment or analysis workflows.

First, select the method that will be used for calls to the Imagga API from the Method pulldown menu. The most common methods for Imagga data ingestion are:

  • GET: For retrieving analysis results, uploading images by URL, and querying recognition results
  • POST: For submitting images for analysis (such as uploading image content for tagging or categorization)

API Endpoint URL​

  1. Enter the URL of the Imagga API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL, including the protocol (https://) and any required path parameters.

    Common Imagga API base URLs include:

    • Image Tagging: https://api.imagga.com/v2/tags — Returns a list of descriptive tags and confidence scores for a given image URL or uploaded image.
    • Image Categorization: https://api.imagga.com/v2/categories/{'{categorizer_id}'} — Classifies an image into a named category set; replace {'{categorizer_id}'} with the identifier of the categorizer to use (e.g., personal_photos or a custom categorizer ID).
    • Color Extraction: https://api.imagga.com/v2/colors — Returns dominant foreground and background colors found in the image.
    • Face Detection: https://api.imagga.com/v2/faces/detections — Detects faces and returns bounding box coordinates and attributes.
    • Content Moderation (NSFW): https://api.imagga.com/v2/categories/nsfw_beta — Returns moderation signals indicating whether image content is safe for work.
    • Image Upload Status / Results: https://api.imagga.com/v2/uploads — Lists previously uploaded images available for analysis.

    All Imagga API endpoints require an image source, provided either as a publicly accessible image URL via the image_url query parameter, or as a previously uploaded image via its image_upload_id. Ensure the image source is specified correctly in your API URL or request parameters.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros — all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/Time macros are particularly useful when paginating through Imagga upload results or filtering analysis records based on date ranges.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime — for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro — i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu — for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when you need to pass specific Imagga upload IDs, categorizer IDs, or image identifiers stored in another Nexla source directly into the API URL for analysis retrieval.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the Imagga API endpoint is needed, you can designate the part of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

For example, the Imagga /tags endpoint returns a JSON object with a top-level result key containing a tags array — each element of this array is one tag with its confidence score. By specifying the path to the tags array, Nexla will treat each tag as an individual record rather than ingesting the entire response as a single record.

Specifying the Path to Data is essential for Imagga API responses, as results are always nested within a result object. Without specifying the correct path, Nexla will treat the entire JSON response as a single record rather than parsing individual analysis results.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.result.tags[*] to access the array of tag objects within the result object).
    Path to Data Examples for Imagga:
    • For the /tags endpoint: enter $.result.tags[*] to treat each tag as a separate record.
    • For the /categories endpoint: enter $.result.categories[*] to treat each category as a separate record.
    • For the /colors endpoint: enter $.result.colors.foreground_colors[*] to retrieve individual foreground colors.
Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the Imagga API response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful for preserving contextual information such as the status field or the original image_upload_id that Imagga includes at the top level of every response.

Metadata paths are particularly useful for preserving Imagga response context — for example, including the HTTP status and message fields alongside each tag or category record to facilitate downstream error handling and auditing.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers may be required for API versioning or content type specifications.

    You do not need to include the Authorization header here — Nexla automatically constructs and includes the Basic Authentication header using the API Key and API Secret stored in your Imagga API credential.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows you to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Imagga API data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.