# Market Overlay

The Sourcing API allows you to access lead and listing data from a variety of used car marketplaces.

This API requires [authentication](https://devhub.autograb.com/my-autograb-api-doc/authentication) and an appropriate license attached to it.

## Market Overlay API <a href="#market-overlay-api" id="market-overlay-api"></a>

When viewing a lead on the web app, a view of similar leads that are currently listed for sale or recently sold is available on the side of the page (the 'Market Overlay'). The Market Overlay API gives you programmatic access to this data, enabling you to show price justifications or re-create our market comparison view for your own purposes.

To access a Market Overlay, you will need to specify a Vehicle ID to search for relevant listings. To retrieve a Vehicle ID, use any of the [Vehicle Search APIs](https://devhub.autograb.com/my-autograb-api-doc/vehicle-search).

When retrieving market data for an Vehicle ID, a best-effort attempt is made to find at least four listings. This search begins by looking at the latest 60 days, and if there is not enough data in this time period, another 10 days of data is added until the minimum quota of four is reached.

If you would like a larger sample of market data, you can specify a `minimum_days` value, and this will override the default minimum of 60 days.

### Example <a href="#example" id="example"></a>

To perform an example request:

<pre class="language-bash"><code class="lang-bash"><strong>curl 'https://api.autograb.com.au/v2/sourcing/market_overlay/{VEHICLE_ID}?region=au' \
</strong>      -H 'ApiKey: {API_KEY}'
</code></pre>

An example payload is included below, although only the first lead is shown to save space:

```json
{
  "success": true,
  "sample_size": 56,
  "days_checked": 60,
  "leads": [
    {
      "id": "nz_autotraderconz_442876",
      "vehicle_id": "4926722097020928",
      "year": 2012,
      "release_year": 2011,
      "release_month": 8,
      "listed_at": "2022-08-11T10:22:07.072Z",
      "removed_at": "2022-09-20T10:22:07.072Z",
      "seller_type": "dealer",
      "color": "Red",
      "state": "VIC",
      "tag_ids": [
        "writeoff",
        "damaged"
      ],
      "price": 15000,
      "kms": 30000,
      "listing_sources": [
        "carsales.com.au",
        "autotrader.com.au"
      ]
    }
  ]
}
```

### Request Parameters <a href="#market-overlay-api" id="market-overlay-api"></a>

<table><thead><tr><th width="260">Name</th><th>Description</th></tr></thead><tbody><tr><td>vehicle_id</td><td>The ID of the vehicle you are requesting a market overlay on.</td></tr><tr><td>minimum_days</td><td><p>The minimum number of days to show listings for</p><p><em>Default value</em> : 60</p></td></tr><tr><td>include_adjacent_years</td><td><p>If enabled, vehicles that were manufactured up to one year before and one year after your chosen vehicle will also be included in the results.</p><p><em>Default value</em> : false</p><p>--true / false</p></td></tr><tr><td>exclude_outliers</td><td><p>If enabled, leads that are considered outliers will be excluded from the results.</p><p><em>Default value</em> : false</p><p>--true / false</p></td></tr><tr><td>exclude_all_delisted</td><td><p>If enabled, leads that are not currently on the market will be excluded from the results.</p><p><em>Default value</em> : false</p><p>--true / false</p></td></tr><tr><td>include_all_active</td><td><p>If enabled, all listings that are currently on the market will be returned, instead of only listings which were uploaded within the specified timeframe (minimum_days). Additionally, if this is enabled, delisted leads will be returned based on the number of days since they were sold, rather than the number of days since they were listed.</p><p><em>Default value</em> : false</p><p>--true / false</p></td></tr><tr><td>include_trash</td><td><p>If enabled, leads that are considered trash, written off, damaged, or missing details will be included in the results. The tag_ids array can then be used to determine if a lead is trash, damaged, etc.</p><p><em>Default value</em> : false</p><p>--true / false</p></td></tr><tr><td>features</td><td><p>Comma-separated array of additional overlay feature codes as specified in your contract</p><p><a href="broken-reference"><em>See available features here.</em></a></p></td></tr><tr><td>odometer_range_min</td><td><p>The minimum range observed against similar vehicles</p><p><em>Example</em> : 50000</p></td></tr><tr><td>odometer_range_max</td><td><p>The maximum range observed against similar vehicles</p><p><em>Example</em> : 100000</p></td></tr><tr><td>region</td><td>--au</td></tr></tbody></table>

## Features

Passing option feature parameters can enhance the market overlay. You can request a single feature or combine them to enrich your responses. Your sales representative must enable a unique permission for each feature.

### **Dealer Contact Details**

This feature will deliver the contact details of the advertising dealership as per the listing. Use `features=dealer_contact_details`

```
"contact_name": "Example Motors",
"contact_number": "+61 3 2568 6587",
```

### **Lead Starting Price**

This feature will deliver the initial price the lead was advertised at. Use `features=lead_starting_price`

```
"starting_price": 73990,
```

### **Lead Price Drops**

This feature will deliver the count of times the price has been dropped. If you would like to know what each drop (or increase) was consider the [Vehicle History](https://github.com/autograb/gitbook-docs/blob/main/gitbook/devhub_au/vehicle-data/vehicle-history.md) endpoint. Use `features=lead_price_drops`

```
"price_drop_count": 2,
```

### **Vehicle RRP**

This feature will deliver the RRP of the vehicle when it was new according to our vehicle data catalogue, the same data and more is available via our [Specifications endpoint](https://github.com/autograb/gitbook-docs/blob/main/gitbook/devhub_au/sourcing/market-overlay/broken-reference). Use `features=vehicle_rrp`

```
"price_when_new": 46990,
```

### **All Listing URLs**

This feature will deliver the listing URLs related to the lead across all sites it is listed on. Use `features=listing_urls`

```json
"listing_details": [
                {
                    "source": "gumtree.com.au",
                    "url": "https://www.gumtree.com.au/s-ad/1319103332/"
                },
                {
                    "source": "autotrader.com.au",
                    "url": "https://www.autotrader.com.au/car/13462144/toyota/hilux/sa/cheltenham/dual-cab/"
                }
            ]
```

### **Primary Cover Image**

This feature will deliver the cover image for each record where available. Each image is stored for 90 days after delisting. Use `features=cover_image`

```json
"cover_image_url": "https://storage.googleapis.com/download/storage/v1/b/ag-img/o/1700380596629%2F402495842_660380.jpg?generation=1700380597213918&alt=media"
```

### **All Images**

This feature will deliver all primary images for each record where available. Each image is stored for 90 days after delisting. Use `features=all_images`

```json
"all_images": [
                "https://storage.googleapis.com/download/storage/v1/b/ag-img/o/1713129285535%2Fd7ec39ad-671b-4b.jpg?generation=1713129287041771&alt=media",
                "https://storage.googleapis.com/download/storage/v1/b/ag-img/o/1713129291498%2Fd3c1928d-a0f4-4f.jpg?generation=1713129292538543&alt=media",
                "https://storage.googleapis.com/download/storage/v1/b/ag-img/o/1713129296398%2Ff982ef2b-a25f-47.jpg?generation=1713129297432084&alt=media",
                "https://storage.googleapis.com/download/storage/v1/b/ag-img/o/1713129300707%2Fb4350079-4f04-4c.jpg?generation=1713129302187962&alt=media",
                "https://storage.googleapis.com/download/storage/v1/b/ag-img/o/1713129306170%2F2a88d686-c4b7-4a.jpg?generation=1713129307655700&alt=media"
            ]
```

### **Primary Listing Description**

This feature will deliver the primary listing description for each record where available. Use `features=primary_description`

```json
 "primary_description": "Near new condition 2022 Jeep Grand Cherokee Limited 4x4 <br> <br> <br> * Panormaic roof <br> * All Wheel Drive <br> * 20-inch Alloy Wheels <br> * 10.1-inch Touchscreen Display <br> * Wireless Apple CarPlay and Android Auto <br> * Leather Seats <br> * Heated & Ventillated front seats <br> * Heated steering wheel <br> * 9 Speaker Premium Audio System <br> * Power liftgate with adjustable height settings <br> * Automatic LED headlamps with Automatic highbeam <br> * Automatic Windscreen Wipers <br> * 10.25\" Multiview Display cluster <br> * 360 ParkView Rear Back-up Camera <br> * Front and Rear Park Assist with Stop <br> * Tyre Pressure Monitoring <br> * Keyless Entry with Push Button Start <br> * Blind Spot Monitoring with Rear Cross-Path Detection <br> * Adaptive Cruise Control with Stop and Go <br> * Active Lane Management <br> * Pedestrian Automatic Emergency Braking (with cyclist detection) <br> <br> We also accept trade ins, So bring down your pride and joy and we can price it on the spot! <br> <br> With easy onsite finance pre approvals available you can be in your new car in no time. <br> <br> WE ARE A PRIVATE OWNED DEALERSHIP JUST 20 MINUTES NORTH OF PERTH CITY,<br/><strong>Motor Mall WA</strong><br/>41 Buckingham Drive Wangara, WA 6065<br/>License number: 29875"
```

### **Registration Plate**

This feature will deliver the vehicle's registration plate in the market overlay payload. Use `features=rego`

```json
"rego": "FDT46H",
```

### **VIN**

This feature will deliver the vehicle's VIN in the market overlay payload. Use `features=VIN`

```json
"vin": "MR0BA3CD900173054",
```

### **Stock Number**

This feature will deliver the vehicle's stock number in the market overlay payload. Use `features=stock_no`

```json
"stock_no": 123ABC,
```

### **Average Kms**

This feature will deliver the average kms and average odometer of the overlay calculated for you in the response. Use `features=avg_kms`

<pre class="language-json"><code class="lang-json"><strong>"avg_odo": 123000,
</strong><strong>"avg_kms":2300,
</strong></code></pre>

### **Average Price**

This feature will deliver the average price of the overlay calculated for you in the response. Use `features=avg_price`

```json
"avg_price": 67664,
```

<br>