Get started with G2 review syndication
  • 20 Nov 2023
  • 9 Minutes to read
  • Dark
    Light

Get started with G2 review syndication

  • Dark
    Light

Article summary

This documentation is intended for G2 review syndication partners and provides an overview of mapping G2 reviews to the products listed on your marketplace.

Before getting started

Your G2 representative will provide you an API key specifically for access to G2's review syndication endpoints. If you do not have a syndication-specific API key, please contact your G2 representative.

For a full list of endpoints available to G2 partners, refer to G2's partner API reference documentation.

Overview

Adding G2 reviews to your marketplace requires the following high-level steps:

  1. Map your products: Use G2's product_mappings endpoint to upload a CSV of your products. G2 will automatically map them based on domain and product name similarity.
  2. Retrieve product mappings: After G2 maps your products, you can retrieve the mapped G2 ID for each product from the product_mappings endpoint.
  3. Access reviews: Once you have the G2 ID for a product, you can access its reviews from the syndication/reviews endpoint.

Mapping your products

G2 offers an automated mapping service that enables you to easily associate a product in your marketplace with its corresponding information on G2.

The product mapping API provides the flexibility to upload CSVs at whatever interval works for your organization. For efficiency, G2 recommends only including updates to your product catalog, rather than sending your full product catalog each time.

You cannot delete product mapping relationships using this API.

1. Generate a CSV of your products

In order to map products in your marketplace to products listed on G2, you must first provide a CSV containing basic information that G2 can use for mapping.

Your CSV must contain the following headers:

  • partner_product_id: The unique identifier for the product in your marketplace.
  • partner_product_name: The product's name.
  • partner_product_vendor_name: The product vendor's name.
  • partner_product_url: The URL for the product's website. This is not the URL for the product's listing on your marketplace.

For example, when populated with data, your CSV should contain the following structure:

partner_product_id partner_product_name partner_product_vendor_name partner_product_url
001 Super Widget Acme Corporation www.superwidget.com
002 Mega Gadget Beta Company www.megagadget.com
003 Hyper Device Gamma Industries www.hyperdevice.com

Make sure your CSV includes these headers in a dedicated header row, and that your headers are in snake case (lowercase letters, underscore-separated).

2. Get the upload URL for your CSV

G2 generates a pre-signed access URL

Endpoint

GET https://data.g2.com/api/v2/product_mappings/csv_upload_url

Query parameters

Parameter Data type Description
api_token string Your API token

Sample request

curl --request GET 'https://data.g2.com/api/v2/product_mappings/csv_upload_url?api_token=API_TOKEN'

Sample response


{
    "data": {
        "type": "url",
        "attributes": {
            "url": "https://product-mapping.s3.amazonaws.com/csv_uploads/accounts-account-1008584/partner_product_upload_20230731132109.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAWSV2Fus-east-3%2Faws4_request&X-Amz-Date=20230731T182110Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d31321eaew3fgs573702e6c"
        }
    }
}

3. Upload the CSV file to your upload URL

You will use the upload URL obtained in the previous step to upload the CSV of your mapping relationships that you generated in step 1.

After uploading your CSV, mapping information will be available within 24 hours.

Arguments

Parameter Data type Description
file path path The relative path to your CSV file.
upload URL string The unique URL you obtained in step 2.

Sample request

curl --request PUT --data @FILE_PATH --header "Content-Type: text/csv" --insecure "UPLOAD_URL"

Sample response

A successful request returns an empty responses with a status code of 200.

Getting product mappings

This endpoint enables you to retrieve the mapping relationships between the products listed in your marketplace and those listed on G2.

Once you have the product mappings available, you can start pulling review content for each product.

G2 recommends querying this endpoint daily using the datetime query parameters to get new product mappings.

Endpoint

GET https://data.g2.com/api/v2/product_mappings/

Query parameters

Parameter Data type Description
filter[created_at_gt] string (ISO 8601) The minimum date and time when a record was created, in ISO 8601 format.
filter[created_at_lt] string (ISO 8601) The maximum date and time when a record was created, in ISO 8601 format.
filter[updated_at_gt] string (ISO 8601) The minimum date and time when a record was last updated, in ISO 8601 format.
filter[updated_at_lt] string (ISO 8601) The maximum date and time when a record was last updated, in ISO 8601 format.
filter[product_id] string The G2 ID for the product.
filter[external_id] string Your unique ID for the product.
fields[product_mappings] string A comma-separated list of fields to include in response. All response fields are included by default.
page[size] integer The number of responses you want to return in your results (min: 1, max: 100). Defaults to 25 if unspecified.
page[number] integer The page number you want to return. Defaults to 1 if unspecified.

Sample request

curl --request GET 'https://data.g2.com/api/v2/product_mappings?api_token=API_TOKEN'

Response fields

Field Data type Description
created_at string (ISO 8601) The date and time when a record was created, in ISO 8601 format.
updated_at string (ISO 8601) The date and time when a record was last updated, in ISO 8601 format.
match_score float The match confidence reported by the algorithm. Values range from 0 (no confidence) to 1 (full confidence).
match_type string Whether mapping was generated [ask-question]
external_id string Your unique ID for the product.
product_id string The G2 ID for the product.
product_name string The name of the product as listed on G2.
partner_product_name string The name of the product as listed on your marketplace.

Sample response


{
    "data": [
        {
            "id": "b2f026ff-21c9-4ff6-ab66-e53ffffssd7",
            "type": "product_mappings",
            "attributes": {
                "created_at": "2023-07-27T16:24:15.647-05:00",
                "updated_at": "2023-07-27T16:24:15.647-05:00",
                "match_score": 0.805310134994837,
                "match_type": "automated",
                "external_id": "99999",
                "product_id": "123456-00a1-1234-abc3-fbdd7bed249a",
                "product_name": "SaaS Company X",
                "partner_product_name": "SaaS Company X"
            }
        }, 
        ...
    ],
    "links": {
        "self": "https://data.g2.com/api/v2/product_mappings?api_token=51aa91e082dea57cf15a9b783819ae350824952de826ee06837f8c7a48887dbb&fields[product_mappings]=created_at",
        "next": "https://data.g2.com/api/v2/product_mappings?api_token=59876a685445657890-97867566ee06837f8c7a48887dbb&fields%5Bproduct_mappings%5D=created_at&page%5Bafter%5D=Mjg3NjY3NA%3D%3D&page%5Bsize%5D=25",
        "prev": null
    },
    "meta": {
        "record_count": 710
    }
}

You can follow links.next to iterate through the next page of results.

Reviews

This endpoint enables you to retrieve reviews for a specific product by G2 ID.

You will need to query the product mappings endpoint to get the G2 ID for the product.

Endpoint

GET https://data.g2.com/api/2018-01-01/syndication/reviews

Query parameters

Parameter Data type Description
filter[product_id]
REQUIRED
string The G2 ID for the reviewed product.
filter[nps_score][] integer A comma-separated list (e.g, 3,4,5) of review ratings. Scores range from 1 to 5.
filter[company_segment][] integer A comma-separated list of reviewer company segments. Possible segments: 179 (Small Business), 180 (Mid-market), 181 (Enterprise)
filter[industry][] string A comma-separated list of reviewer industries.
filter[category_ids][] string A comma-separated list of IDs for the G2 categories you want reviews from.
filter[role][] string A comma-separated list of reviewer job roles.
filter[regions][] string A comma-separated list of reviewer global regions.
filter[country_name][] string A comma-separated list of country names.
filter[updated_at_gt] string (ISO 8601) The minimum date and time when a review was last updated, in ISO 8601 format.
filter[updated_at_lt] string (ISO 8601) The maximum date and time when a review was last updated, in ISO 8601 format.
filter[comment_answer_values_exclude] string A comma-separated list of keywords you want to exclude. Reviews containing a matching keyword will not be included in the response.
filter[excluding] string A comma-separated list of review IDs you want to exclude from the response.
page[size] integer The number of responses you want to return in your results (min: 1, max: 100). Defaults to 25 if unspecified.
page[number] integer The page number you want to return. Defaults to 1 if unspecified.

Sample request

curl --request GET 'https://data.g2.com/api/2018-01-01/syndication/reviews?filter[product_id]=PRODUCT_ID&page[size]=50&api_token=API_TOKEN'

Response fields

data

The data object contains an array of reviews. Each review contains the following information.

Field Data type Description
default_sort float The numerical score for the review, used to sort review responses.
is_public boolean Whether the review response is public.
slug string The URL slug for the G2 review.
percent_complete float The percent of required questions and optional product feature questions answered by the reviewer. Values range from 0 to 1.
submitted_at string (ISO 8601) The date and time when the review was submitted, in ISO 8601 format.
title string The title for the review, entered by the reviewer.
url string The full URL for the G2 review.
answers object An object containing the free-response questions and answers on the G2 review form.
published_at string (ISO 8601) The date and time when the review was submitted, in ISO 8601 format.
regions array An array of each the global regions associated with the reviewer.
country_name string The reviewer's country.
product_name string The name of the reviewed product as listed on G2.
source string The source of the review.
review_incentive boolean Whether the reviewer received an incentive for submitting their review.
star_rating float The star rating associated with the review, ranging from 0 to 5.
user object Basic information about the reviewer, including their name, company, and title.
verified_current_user boolean Whether the reviewer was a current user of the product at the time of review submission.
comment_present boolean Whether the review has a response from a G2 user or the product vendor.
official_response_present boolean Whether the review has a response from the product vendor.
attribution object Use the information in this section to create a backlink to the review on G2.

Sample response


{
    "data": [
        {
            "id": "7853817",
            "type": "survey_responses",
            "attributes": {
                "default_sort": 7.10001659856123,
                "is_public": true,
                "slug": "g2-marketing-solutions-review-7853817",
                "percent_complete": 0.9032258064516129,
                "submitted_at": "2023-03-21T11:50:15.920-05:00",
                "user_updated_at": "2023-03-21T11:50:15.964-05:00",
                "title": "Great team and great product",
                "url": "https://www.g2.com/products/g2-seller-solutions/reviews/g2-marketing-solutions-review-7853817",
                "answers": {
                    "love": {
                        "text": "What do you like best about the product?",
                        "value": "G2 is a great platform! We enjoy working with the G2 team..."
                    },
                    "hate": {
                        "text": "What do you dislike about the product?",
                        "value": "Price can be pretty expensive, however, given the offerings I believe the cost makes sense."
                    },
                    "benefits": {
                        "text": "What problems is the product solving and how is that benefiting you?",
                        "value": "A place to collect quality reviews but also a way to leverage those reviews in their quarterly Grid Reports which allow us to make use of them in campaigns and with our sales organization..."
                    }
                },
                "published_at": "2023-03-21T13:48:06.233-05:00",
                "regions": [
                    "Americas",
                    "North America"
                ],
                "country_name": "United States",
                "product_name": "G2 Marketing Solutions",
                "source": "Organic review. This review was written entirely without invitation or incentive from G2, a seller, or an affiliate.",
                "review_incentive": false,
                "star_rating": 5.0,
                "user": {
                    "industry": "Computer Software",
                    "name": "Alexandra C.",
                    "image": null,
                    "company": null,
                    "title": null,
                    "company_segment": "Enterprise (> 1000 emp.)"
                },
                "verified_current_user": true,
                "comment_present": true,
                "official_response_present": false,
                "attribution": {
                    "text": "Verified by G2",
                    "url": "https://www.g2.com/products/g2-seller-solutions/reviews/g2-marketing-solutions-review-7853817",
                    "logo": "/assets/g2-logo-rorange-6ca9fc7c312e493b94cd245bf797ef564f27b3544d0c3930706d890859a1f92e.svg"
                }
            }
        },
        ...
    ], 
    ...
}

meta

The meta object contains high-level information about the reviews included in your response.

Field Data type Description
aggregates array An array of objects. Each object represents a different method for aggregating the reviews in the response.

For example, the industry aggregation lists each industry returned in your response, and the corresponding number of reviews in each industry.
record_count integer The total number of reviews returned in your response.
page_count integer The number of pages in your response.
product object Details about the reviewed product, including its name, description, web domain, average rating, review count, G2 URL, and other basic information.
rating float The overall rating for the reviewed product. Values range from 1 to 10.

Sample response


{
    ...,
    "meta": {
        "aggregates": [
            {
                "filter_name": "nps_score",
                "nested_filter_name": null,
                "collection": [
                    {
                        "id": 5,
                        "text": "5 star",
                        "count": 60,
                        "checked": false,
                        "nested_boxes": []
                    },
                    {
                        "id": 4,
                        "text": "4 star",
                        "count": 15,
                        "checked": false,
                        "nested_boxes": []
                    }
                    ...
                ],
                "expanded": true
            },
            ...,
            {
                "filter_name": "industry",
                "nested_filter_name": null,
                "collection": [
                    {
                        "id": 274,
                        "text": "Computer Software",
                        "count": 34,
                        "checked": false,
                        "nested_boxes": []
                    },
                    {
                        "id": 313,
                        "text": "Information Technology and Services",
                        "count": 18,
                        "checked": false,
                        "nested_boxes": []
                    },
                    ...
                ],
                "expanded": false
            },
            ...
        ],
        "record_count": 77,
        "page_count": 8,
        "product": {
            "name": "G2 Marketing Solutions",
            "domain": "g2.com",
            "slug": "g2-seller-solutions",
            "product_type": "Software",
            "star_rating": 4.6,
            "avg_rating": "9.2",
            "detail_description": "G2 is the world's largest and most trusted software marketplace...",
            "review_count": 666,
            "image_url": "https://images.g2crowd.com/uploads/product/image/1233ef954d868794f19ce75837789fe8/g2-seller-solutions.png",
            "public_detail_url": "https://sell.g2.com/",
            "g2crowd_url": "https://www.g2.com/products/g2-seller-solutions/reviews",
            "write_review_url": "https://www.g2.com/products/g2-seller-solutions/take_survey"
        },
        "rating": 9.2
    }
}