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_idpartner_product_namepartner_product_vendor_namepartner_product_url
001Super WidgetAcme Corporationwww.superwidget.com
002Mega GadgetBeta Companywww.megagadget.com
003Hyper DeviceGamma Industrieswww.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

ParameterData typeDescription
api_tokenstringYour 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

ParameterData typeDescription
file pathpathThe relative path to your CSV file.
upload URLstringThe 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

ParameterData typeDescription
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]stringThe G2 ID for the product.
filter[external_id]stringYour unique ID for the product.
fields[product_mappings]stringA comma-separated list of fields to include in response. All response fields are included by default.
page[size]integerThe number of responses you want to return in your results (min: 1, max: 100). Defaults to 25 if unspecified.
page[number]integerThe 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

FieldData typeDescription
created_atstring (ISO 8601)The date and time when a record was created, in ISO 8601 format.
updated_atstring (ISO 8601)The date and time when a record was last updated, in ISO 8601 format.
match_scorefloatThe match confidence reported by the algorithm. Values range from 0 (no confidence) to 1 (full confidence).
match_typestringWhether mapping was generated [ask-question]
external_idstringYour unique ID for the product.
product_idstringThe G2 ID for the product.
product_namestringThe name of the product as listed on G2.
partner_product_namestringThe 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

ParameterData typeDescription
filter[product_id]
REQUIRED
stringThe G2 ID for the reviewed product.
filter[nps_score][]integerA comma-separated list (e.g, 3,4,5) of review ratings. Scores range from 1 to 5.
filter[company_segment][]integerA comma-separated list of reviewer company segments. Possible segments: 179 (Small Business), 180 (Mid-market), 181 (Enterprise)
filter[industry][]stringA comma-separated list of reviewer industries.
filter[category_ids][]stringA comma-separated list of IDs for the G2 categories you want reviews from.
filter[role][]stringA comma-separated list of reviewer job roles.
filter[regions][]stringA comma-separated list of reviewer global regions.
filter[country_name][]stringA 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]stringA comma-separated list of keywords you want to exclude. Reviews containing a matching keyword will not be included in the response.
filter[excluding]stringA comma-separated list of review IDs you want to exclude from the response.
page[size]integerThe number of responses you want to return in your results (min: 1, max: 100). Defaults to 25 if unspecified.
page[number]integerThe 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.

FieldData typeDescription
default_sortfloatThe numerical score for the review, used to sort review responses.
is_publicbooleanWhether the review response is public.
slugstringThe URL slug for the G2 review.
percent_completefloatThe percent of required questions and optional product feature questions answered by the reviewer. Values range from 0 to 1.
submitted_atstring (ISO 8601)The date and time when the review was submitted, in ISO 8601 format.
titlestringThe title for the review, entered by the reviewer.
urlstringThe full URL for the G2 review.
answersobjectAn object containing the free-response questions and answers on the G2 review form.
published_atstring (ISO 8601)The date and time when the review was submitted, in ISO 8601 format.
regionsarrayAn array of each the global regions associated with the reviewer.
country_namestringThe reviewer's country.
product_namestringThe name of the reviewed product as listed on G2.
sourcestringThe source of the review.
review_incentivebooleanWhether the reviewer received an incentive for submitting their review.
star_ratingfloatThe star rating associated with the review, ranging from 0 to 5.
userobjectBasic information about the reviewer, including their name, company, and title.
verified_current_userbooleanWhether the reviewer was a current user of the product at the time of review submission.
comment_presentbooleanWhether the review has a response from a G2 user or the product vendor.
official_response_presentbooleanWhether the review has a response from the product vendor.
attributionobjectUse 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.

FieldData typeDescription
aggregatesarrayAn 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_countintegerThe total number of reviews returned in your response.
page_countintegerThe number of pages in your response.
productobjectDetails about the reviewed product, including its name, description, web domain, average rating, review count, G2 URL, and other basic information.
ratingfloatThe 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
    }
}