- 20 Nov 2023
- 9 Minutes to read
- DarkLight
Get started with G2 review syndication
- Updated on 20 Nov 2023
- 9 Minutes to read
- DarkLight
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:
- 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. - Retrieve product mappings: After G2 maps your products, you can retrieve the mapped G2 ID for each product from the
product_mappings
endpoint. - 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_ | 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_ | 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
}
}