Basic API Queries

The basics of working with the Mohawk Automation (API) and some simple example queries that can be executed.

Inspirational applications - queries

In this document, we give some simple example queries. This will help you get started quickly and get a grasp on the Mohawk Automation (API).

What can you find here:

/free_text
passing multiple parameters

Free text search

Situation: a customer is looking for an item, or keyword, that is not supported by any of our standard endpoints (license plate, vin, nickname, email or phone number).

For example, say that you are looking for ads in the last 3 months that contain the keyword = Gucci bag.

Seeing how there is no endpoint that allows you to search for this particular identifier directly, we suggest you use the /free_text path.

Solution:

Python:

import requests

url = 'https://api.mohawkanalytics.com/classifiedads/gb/v1/free_text'

headers = {'API-Key':'<YOUR_API_KEY>'}
data = {'free_text':'gucci bag', "limit": 20, "offset": 0, "select": None}

resp = requests.post(url, data=data, headers=headers)

print(resp.json())

Curl:

curl  -X 'POST' \
      'https://api.mohawkanalytics.com/classifiedads/gb/v1/free_text' \
      -H 'accept: application/json' \
      -H 'API-Key: <YOUR_API_KEY>' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'free_text=%22gucci%20bag%22&limit=20&offset=0&select=&date_start=&date_end='

Note: that searching for Volvo V40 is interpreted as searching for “Volvo" AND "V40" whereas searching for “Volvo V40" is interpreted as searching for "Volvo V40". Single double quotation marks, that is ", in a search is ignored by our API and yield similar results as the former examples.

The endpoint handles the text inside quotation marks "" as well. For example, when the search query is: Volvo V40 parts "damaged car" It will translate to: search: "Volvo" AND search: "V40" AND search:"parts" search: "damaged car".

With the following (part of) the response:

...
'count': 62037,
'documents': [{'fields': {'image_url': ['https://i.ebayimg.com/images/g/On8AAOSwDfdixtI7/s-l1200.jpg',
'https://i.ebayimg.com/images/g/10MAAOSwjfxixtI8/s-l1200.jpg',
'https://i.ebayimg.com/images/g/O5UAAOSwdMNixtI~/s-l1200.jpg',
'https://i.ebayimg.com/images/g/fa4AAOSwmpNixtJq/s-l1200.jpg',
'https://i.ebayimg.com/images/g/rMIAAOSwophixtJB/s-l1200.jpg',
'https://i.ebayimg.com/images/g/fJoAAOSwnGhixtJC/s-l1200.jpg',
'https://i.ebayimg.com/images/g/LSoAAOSwcR9ixtJD/s-l1200.jpg',
'https://i.ebayimg.com/images/g/ShUAAOSwjy9ixtJo/s-l1200.jpg'],
'page-title': 'gucci GG messenger bag | eBay',
'price': '20000.0',
'text': 'Payments: *From £10 per month for 24 months. See payment information- for PayPal Credit, opens in a new window or tab Payments: Payments: eBay item number: 374167953583 Seller assumes all responsibility for this listing. Item specifics Condition: Used: An item that has been previously worn. See the seller’s listing for full details and ... Read moreabout the conditionUsed: An item that has been previously worn. See the seller’s listing for full details and description of any imperfections. See all condition definitionsopens in a new window or tab Brand: Gucci Department: Men Style: Messenger Bag Material: Leather Colour: Black Payment details Payment methods Accepted, Eligibility for PayPal Credit is determined at checkout. Representative example Purchase rate p.a. (variable) 21.9% Representative APR (variable) 21.9% APR Assumed Credit Limit £1,200 eBay (UK) Limited is an appointed representative of Product Partnerships LimitedLearn more about Product Partnerships Limited - opens in a new window or tab (of Suite D2 Joseph’s Well, Hanover Walk, Leeds LS3 1AB) which is authorised and regulated by the Financial Conduct Authority (with firm reference number 626349). eBay (UK) Limited acts as a credit broker not a lender. We may receive commission if your application for credit is successful, the commission does not affect the amount you will pay under your agreement. Finance is provided by PayPal Credit (a trading name of PayPal (Europe) S.à r.l. et Cie, S.C.A. Société en Commandite par Actions Registered Office: 22-24 Boulevard Royal L-2449, Luxembourg). If you would like to know how we handle complaints, please click hereLearn more about Product Partnerships Limited - opens in a new window or tab. To access our initial disclosure document, please click hereLearn more about Product Partnerships Limited - opens in a new window or tab. Learn MoreSee terms for PayPal Credit - opens in a new window or tab',
'url': 'https://www.ebay.co.uk/itm/374167953583?hash=item571e25e0af:g:On8AAOSwDfdixtI7',
'published_estimated': '2022-07-08 04:59:10 +0000'}}],
'mohawk_search': 'https://mohawk.legentic.com/#/login/%7B%22search%22:%7B%22text%22:%22gucci%20bag%22%7D,%22scope%22:%22general%22,%22apis%22:%7B%22api_1%22:%22classifiedads_gb%22%7D%7D',
'paging': {'next': {'limit': '1',
'offset': '1',
'select': 'published_estimated,license_plate_number,telephone,email,author,author-uri,price,url,category,name,page-title,text,location,classifiedads_id,image_url,vin',
'free_text': 'gucci bag'}
...

Following the author-URI reveals more information about the user, including name and phone number.

The possibilities are endless, this is a simple example. Many more can be imagined. The approach for the following endpoints follows a similar pattern:

/phone
/email
/nickname
/vin
/license_plate

Multiple parameters search

Situation: a query needs to be constrained for various reasons. One can imagine that you can only ingest a single item at a time, or that the query needs to be constrained in time (last x months or years) in order to be relevant. Or that the price range needs to be a constraint.

Solution: multiple parameters can be passed through the API in order to limit the responses. You can use limit, offset, date-start and date-end as potential limiters. Exemplified below:

Python:

import requests
from datetime import date, timedelta

today = date.today()
previous = date.today() - timedelta(days=90)

url = 'https://api.mohawkanalytics.com/classifiedads/gb/v1/license_plate'

headers = {'API-Key':'<YOUR_API_KEY>'}
data = {'license_plate':'EN18UWW', 'limit':'20', 'date_start': previous ,'date_end': today }

resp = requests.post(url, data=data, headers=headers)

print(resp.json())

Curl:

curl  -X 'POST' \
      'https://api.mohawkanalytics.com/classifiedads/gb/v1/license_plate' \
      -H 'accept: application/json' \
      -H 'API-Key: <YOUR_API_KEY>' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'license_plate= EN18UWW&limit=2&offset=0&date_start=2019-01-01&date_end=2022-06-01'

With a single response fitting both the limit = 2 and the date start and end condition:

...
'count': 8,
 'documents': [{'fields': {'author': 'Pulman SEAT',
    'image_url': 'https://cdn-csnetworkstock.s3.amazonaws.com/ford/kuga/57159/40817473/ford_kuga_1_l.jpg',
    'page-title': 'Used 2018 Ford Kuga 2.0 TDCi 180 Titanium X 5dr Auto Not Specified 32,120 miles in white for sale | CarSite',
    'classifiedads_id': 'www.carsite.co.uk-c6f4458c',
    'url': 'https://www.carsite.co.uk/used-car/ford/kuga/hcp_d-3be6428c_c6f4458c',
    'license_plate_number': 'EN18UWW',
    'published_estimated': '2022-07-11 07:19:58 +0000',
    'price': '18500.0',
    'name': 'Used 2018 Ford Kuga 2.0 TDCi 180 Titanium X 5dr Auto in Sunderland',
    'location': 'Burntland Avenue, Sunderland, Durham SR52ET',
    'author-uri': 'https://www.carsite.co.uk/dealers/pulman-seat-hcp_d-3be6428c',
    'text': 'Ford Kuga £18,500 2.0 TDCi 180 Titanium X 5dr Auto Call the dealer Click to call the dealer Mileage: 32,120 Transmission: Automatic Doors: 5 Engine Size: 2000 cc Body Style: - Fuel Type: Diesel Colour: white Registration: EN18UWW Year: 2018 Price: £18,500 Pulman SEAT Description Bluetooth system, EPAS, Rear parking sensor, SYNC Emergency Assistance, Trip computer, Auxiliary socket for external device, Remote audio controls on steering wheel, USB connection, Auto dimming rear view mirror, Automatic headlights, Bi-Xenon headlights with dynamic bending and active beam shape, Body colour bumpers, Body colour rear spoiler, Electric folding mirrors, Electric panoramic glass sunroof, Electrically heated door mirrors, Front scuff plate, Headlight washer jets, LED daytime running lights, LED tail lights, Power front and rear windows, Quickclear heated windscreen, Rain sensor windscreen wipers, Rear diffuser, Tailgate wash/wipe, Twin exhaust pipes, 10 way electric power adjustable drivers seat, 6 way manually adjustable passenger seat, 60/40 split/folding rear back and cushion, Auxiliary power socket in luggage area, Centre console with stowage tray/bottle holder/CD stowage/front and rear 12V power point, Driver seat lumbar adjustment, Driver/passenger front seatback pockets, Dual electronic automatic temperature control, Folding rear centre armrest, Footwell courtesy lights front and rear, Front floor mats, Front head restraints, Front overhead courtesy lights with theatre style dimming and delay, Front/rear reading lights, Gearshift paddles, Heated front seats, Isofix system on outer rear seats, Leather gearknob, Leather steering wheel, Multi-colour ambient interior lighting, Passenger lumbar support, Reach + rake adjustable steering column, Rear floor mats, Rear head restraints, Salerno leather upholstery, Sports style front seats, Stowage unit in upper instrument panel, Tie down hooks, Tonneau cover, Variable intensity instrument illumination, 3 point seatbelts on all 3 rear seats, ABS/EBD, Driver and passenger airbags, Driver and passenger side airbags, Electric traction assist system, Electronic parking brake, ESP+EBA, Front and rear curtain airbags, Hill start assist, Intelligent Protection System (IPS), Tyre pressure monitoring system, Immobiliser, Keyless entry system with hands free boot opening, Keyless Start, Locking wheel nuts, Remote central locking, Thatcham Cat.1 alarm, Mini steel spare wheel, Follow this link Used Ford Kuga in Sunderland to search for other Ford Kuga local to Sunderland. Click this link Ford Kuga in Tyne and Wear to widen your search to the whole Tyne and Wear area. Ford Kuga £18,500 2.0 TDCi 180 Titanium X 5dr Auto Call the dealer Click to call the dealer Mileage: 32,120 Transmission: Automatic Doors: 5 Engine Size: 2000 cc Body Style: - Fuel Type: Diesel Colour: white Registration: EN18UWW Year: 2018 Price: £18,500 Pulman SEAT Description Bluetooth system, EPAS, Rear parking sensor, SYNC Emergency Assistance, Trip computer, Auxiliary socket for external device, Remote audio controls on steering wheel, USB connection, Auto dimming rear view mirror, Automatic headlights, Bi-Xenon headlights with dynamic bending and active beam shape, Body colour bumpers, Body colour rear spoiler, Electric folding mirrors, Electric panoramic glass sunroof, Electrically heated door mirrors, Front scuff plate, Headlight washer jets, LED daytime running lights, LED tail lights, Power front and rear windows, Quickclear heated windscreen, Rain sensor windscreen wipers, Rear diffuser, Tailgate wash/wipe, Twin exhaust pipes, 10 way electric power adjustable drivers seat, 6 way manually adjustable passenger seat, 60/40 split/folding rear back and cushion, Auxiliary power socket in luggage area, Centre console with stowage tray/bottle holder/CD stowage/front and rear 12V power point, Driver seat lumbar adjustment, Driver/passenger front seatback pockets, Dual electronic automatic temperature control, Folding rear centre armrest, Footwell courtesy lights front and rear, Front floor mats, Front head restraints, Front overhead courtesy lights with theatre style dimming and delay, Front/rear reading lights, Gearshift paddles, Heated front seats, Isofix system on outer rear seats, Leather gearknob, Leather steering wheel, Multi-colour ambient interior lighting, Passenger lumbar support, Reach + rake adjustable steering column, Rear floor mats, Rear head restraints, Salerno leather upholstery, Sports style front seats, Stowage unit in upper instrument panel, Tie down hooks, Tonneau cover, Variable intensity instrument illumination, 3 point seatbelts on all 3 rear seats, ABS/EBD, Driver and passenger airbags, Driver and passenger side airbags, Electric traction assist system, Electronic parking brake, ESP+EBA, Front and rear curtain airbags, Hill start assist, Intelligent Protection System (IPS), Tyre pressure monitoring system, Immobiliser, Keyless entry system with hands free boot opening, Keyless Start, Locking wheel nuts, Remote central locking, Thatcham Cat.1 alarm, Mini steel spare wheel,',
    'category': 'Kuga'}}
...

Now, it's time to look at more complicated use cases in the Advanced Queries section.