Product Data Enrichment with Postman and JSON

For this guide, we're going to assume the following you're interested in using Datafiniti's product data enrichment to enrich an existing line separated JSON file of Gtins. There are four steps to run a product data enrichment using JSON:

  1. Select your enrichment file
  2. Set your field_parameter
  3. Configure your format, query, & view
  4. Start your download

Select your Enrichment File

Shown here is an example of a acceptable line separate JSON file with the correct keys to match GTINS. We will be using this file for the example.

{"id":"ByfmlncBccoD1xujZi_h","brand":"DELL","gtins":884116385257}
{"id":"NSvlJ3gBUbef_7uTmrZ0","brand":"iVIEW","gtins":880010018154}
{"id":"AW5IbZIW0Rejpz6vwAXt","brand":"DELL","gtins":884116316909}
{"id":"dgiPbXIBvxj1aRneT4Do","brand":"Lenovo","gtins":194552049454}
{"id":"AVwjfl5Pnnc1JgDc5uVT","brand":"Microsoft","gtins":"0889842170634"}
{"id":"b1HdPnIBo6SyyXo05RFA","brand":"HP","gtins":195122090630}
{"id":"ufzNCHUBo6SyyXo0Cbhh","brand":"HP","gtins":880118668855}
{"id":"V3Lmn3IBo6SyyXo08van","brand":"Lenovo","gtins":194778022286}
{"id":"hiblJ3gBPkqI1fUQnVR3","brand":"iVIEW","gtins":880010018116}
{"id":"DYxQZXEBPkqI1fUQQmtB","brand":"Microsoft","gtins":889842294590}
{"id":"F-ej_3EBvxj1aRneqIxF","brand":"Microsoft","gtins":889842594003}
{"id":"5u9xbHYBUbef_7uTUCwb","brand":"ASUS","gtins":192876840085}
{"id":"cQrmQHcBPkqI1fUQlT3h","brand":"HP","gtins":196068441692}
{"id":"AV13Ck1nglJLPUi8O7f5","brand":"HP","gtins":"0825633419421"}
{"id":"HBCgGXcBvxj1aRneekAa","brand":"Lenovo","gtins":195477750357}
{"id":"wYybZHEBPkqI1fUQJCDZ","brand":"Microsoft","gtins":889842388244}
{"id":"kiw2NXMBPkqI1fUQQYJW","brand":"Microsoft","gtins":889842265903}
{"id":"l_E3AngBYEtaI8J07_Y-","brand":"ASUS","gtins":192876803684}
{"id":"AW-1PyF-0Rejpz6vIIv6","brand":"Microsoft","gtins":889842784145}
{"id":"AVpe8Qmu1cnluZ0-aV3y","brand":"HP","gtins":680596404057}

🚧

Line Separate JSON File

Our enrichment search API will not allow a regular JSON file as submittable comparison file. Please be sure to convert you JSON to a line separated file before submission. Common error you may see in this case:

    "Invalid file type, must be csv or text file."

Set your enrichment file as the field_parameter file.

14311431

Set Your field_parameter

For the field parameter we want to make sure that the Datafiniti schema field is select and matching inside the txt file. This will allow the enrichment API to target submitted GTINS in our case here.

16151615

Configure Your Format, Query, & View

Your format will determine the output file type of the enrichment download you wish to start. This can be set to either of CSV or JSON. For this example we will set it to CSV.
The query parameter is used to refine the data we will use for enrichment. It can be as simple as *${field_parameter}:**

🚧

Query - Download Time

We strongly advise against general field_parameter:*, for this will search through a large pool of products. Therefore the more specific your query is, the faster your enrichment job will be.

If this case that is why we are targeting the following:

  1. Anything with a GTINs in the record
  2. categories = cosmetics
  3. Has been updated in the last week's date range

Finally the view is used to specify which fields you want added to your data. If no view is provided, we will add all fields from matching records as we do for our Default view for the {data_type}/search API.

Your finally parameter should be setup as the following.

15991599

Listed below is a cURL POST to import this example into Postman.

curl --location --request POST 'https://api.datafiniti.co/v4/product/search/enrichment' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1N20zaDB3cmVoY21rZDkwZDNxZThrZzB5dXUwM2hkcyIsImlzcyI6ImRhdGFmaW5pdGkuY28ifQ.o8UWW-x-awyD8M_XldvKmKaNAWfwCUFFm9MuPZjeOz1a-2_1rNVLp_SJmfFKTs1Lk4061L0P_trlvmKG6ld5LSlamEfbPGAVfkRDU75m7K_RP0PuyhcyPbbHr-pNjEzAi2LC8tEcQh557FKo_tBRVRCJ8cMu_8cMMdxj2WjflGfqrxyxMDyxlHdakHZ4qoi2gyNOzOffrkiFaOFx_YhfIJ0BqZsTW_k1rm64Z98nXzb8SigP_gsUzHKlkDqCS7OCO5xRtVXpvdx5WNwmGNwSWm52gq191o03W8ZY-jirMVvAgpZrt4V0NYo6jeTnXweoUb_VMm64Tcj2gjmPhZKjRVHgwZEpRA1T6uVTr5CaWlOT8XC2_wUda2a2m88uEWoB9wbao5SZ2xcNU1jEwhlkSoXtxvWQudMhDfUQPmM96rwEouiqgwSOxTJAt91gtBwLgoStkpRBWMOa2EgxlsJYlWQtQcGgFiuAZfL8gnHq7jMmCegcSso7lThO_0wiLmWfpqqVaI6i7xCeL5I4BK5osf3CO_aSPkV2IlVwp6roVh3VEpAKOrgqb5evq6KKOFKiw_6XH-W2xhsn2OQLHZ1d7HzZkcTpXoLDLEtgslIOdjANJyl13yYEUNRBP927O6ny4MfftY5uNvuf28Lj6OGHGCNS5aFMgd0qskPie-3FpfM' \
--form '[email protected]"/C:/Users/Leonard/Downloads/productEnrichment20.txt"' \
--form 'format="csv"' \
--form 'num_records="20"' \
--form 'query="gtins:* AND categories:comestics AND dateUpdated[2022-09-31 TO *]"' \
--form 'view=""'

Start Your Download

Once you Send your Postman request for the enrichment download you will not be charged credits immediately. It will create a download response. We recommend holding on to the download ID for that will allow your to access the data once the status is complete. For more on how to manage your downloads you can visit here.

Example Enrichment Download Response:

"status": "completed",
    "num_downloaded": 19,
    "num_records_suppressed": 0,
    "total_cost": 19,
    "sort": true,
    "format": "json",
    "suppressed_fields": [],
    "enriched_fields": [
        {
            "field": "gtins",
            "s3Key": "production/126609/1665067765258-productEnrichment20.txt"
        }
    ],
    "_id": 185115,
    "user": 126609,
    "query": "name:(laptop) AND taxonomy:* AND gtins:* AND taxonomyLevel3:\"computers & tablets\"",
    "num_records": 20,
    "data_type": "product",
    "results": [
        "https://datafiniti-downloads.s3.amazonaws.com/126609/185115_1.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221006T151736Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604800&X-Amz-Credential=AKIAZSCI425AD5EKHVNH%2F20221006%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e35aaeaf9e192a7e6009ef83c18502da154b61e546cef7540528b6ce12af1d81"
    ],
    "date_started": "2022-10-06T14:49:25.857Z",
    "date_updated": "2022-10-06T15:17:36.726Z",
    "is_suppression_job": false,
    "is_enrichment_job": true,
    "id": "185115"

🚧

Credit Usage

Please note the number of num_record will not be charged against your account upon submitting this request. You will only be charged credits per record matched. Since Enrichment charges credits per the batch file you are enriching data from, you may be overcharged credits to your account upon submitting a enrichment request. If you do not know if overcharging is enable / disable on your account you may contact [email protected] to find this info out.