# LeBonCoin-API

LeBonCoin JS API is an API to obtain the data from leboncoin.fr in a fluent JS API.

# Features

• Search on leboncoin.fr with all functionality available leboncoin.fr
• Get the detailed page of an item
• Get the phone number of the seller (convert the image to string) /!\ This API have an unknown usage limit

# Example

const leboncoin = require('leboncoin-api');
var search = new leboncoin.Search()
    .setPage(1)
    .setQuery("renove")
    .setFilter(leboncoin.FILTERS.PARTICULIER)
    .setCategory("locations")
    .setRegion("ile_de_france")
    .addSearchExtra("price", {min: 1500, max: 2000}) // will add a range of price
    .addSearchExtra('furnished', ["1", "Non meublé"]); // will add enums for Meublé and Non meublé

search.run().then(function (data) {
    console.log(data.page); // the current page
    console.log(data.nbResult); // the number of results for this search
    console.log(data.results); // the array of results
    data.results[0].getDetails().then(function (details) {
        console.log(details); // the item 0 with more data such as description, all images, author, ...
    }, function (err) {
        console.error(err);
    });
    data.results[0].getPhoneNumber().then(function (phoneNumer) {
        console.log(phoneNumer); // the phone number of the author if available
    }, function (err) {
        console.error(err); // if the phone number is not available or not parsable (image -> string)
    });
}, function (err) {
    console.error(err);
});

# Search API

const leboncoin = require('leboncoin-api');
var search = new leboncoin.Search()

# run();

• Parameter http options: Object default: search.getUrlOptions()
• Parameter body parameter: Object default: search.getBodyParams()
• Return type: Promise<Item[]>

Make search request on leboncoin.fr .

const results = await search.run();

# setQuery()

• Parameter: String
• Return type: Search

Define the textual search query, by default the query search in the description and in the title. See setTitleOnly to only search in the title. The query can contain specific keywords like OR , NOT , "exact match" as specified here: https://www2.leboncoin.fr/tips.htm .

search.setQuery("Golf NOT GTI");

# setTitleOnly()

• Parameter: boolean
• Default: false
• Return type: Search

Define if the query should only match the title of the item.

search.setTitleOnly(true);

# setPage()

• Parameter: Integer
• Default: 1
• Return type: Search

Define the page you want the results for, the page start at 1. See setLimit to define the number of results per page.

search.setPage(1);

# setLimit()

• Parameter: Integer
• Default: 35
• Return type: Search

Define the number of results per page.

search.setLimit(10);

# setSort()

• Parameter: {"sort_by":"date", "sort_order": "asc"}
• Default: {"sort_by":"date", "sort_order": "asc"}
• Return type: Search

Define the sorting order of the results. sort_by can be date or price and sort_order can be asc or dsc .

search.setSort({
    "sort_by": "date",
    "sort_order": "asc"
});

# setFilter()

• Parameter: leboncoin.FILTERS.ALL|leboncoin.FILTERS.PARTICULIER|leboncoin.FILTERS.PROFESSIONNELS
• Default: leboncoin.FILTERS.ALL
• Return type: Search

Define the type of user that posted the item.

search.setFilter(leboncoin.FILTERS.PARTICULIER);

# setCategory()

• Parameter: String
• Return type: Search

Define the category of the search. Categories contains the complete list of possible values.

search.setCategory("locations");

# setUrgencyOnly()

• Parameter: boolean
• Default: false
• Return type: Search

Search only urgent item.

search.setUrgencyOnly(true);

# setRegion()

• Parameter: String
• Return type: Search

Define the region of the search. Regions contains the complete list of possible values.

search.setRegion("aquitaine");

# setDepartment()

• Parameter: String
• Return type: Search

Define the department of the search. Departments contains the complete list of possible values.

search.setDepartment("aisne");

# setLocation()

• Parameter: Array
• Return type: Search

Define where the item is located using the zip code of the city.

search.setLocation([{"zipcode": "78100"},{"zipcode": "78000"}]);

# setArea()

• Parameter: {"lat": X, "lng": X, "radius": X}
• Return type: Search

Define the area where the item is located using GPS coordinate. lat and lng define the latitude and longitude of the circle of the defined radius (in meter).

search.setArea({"lat": 45.7679705, "lng": 4.8637901999999995, "radius": 30000})

# addSearchExtra()

• Parameter: The key of the extra search parameter
• Parameter: The value of the extra search parameter
• Return type: Search

Define extra search parameter for the search. Each category has different extra parameter you can obtain the key and value by looking at the HTML content of leboncoin.fr page.

search.addSearchExtra("price", {min: 1500, max: 2000}) // will add a range of price
search.addSearchExtra('furnished', ["1", "Non meublé"]); // will add enums for Meublé and Non meublé

# Item

const leboncoin = require('leboncoin-api');
var item = (await new leboncoin.Search().setQuery("iPhone X").setLimit(1).run())[0]

# title

• Type: String

The title of the item.

# description

• Type: String

The full description of the item.

# category

• Type: String

The category of the item.

# link

• Type: url

The url of the item.

# images

• Type: Array

An array of pictures of the item.

# location

• Type: String

The location of the item.

# urgent

• Type: boolean

true if the sell is urgent.

# price

• Type: Integer

The price of the item in euro.

# date

• Type: Date

The date when the item has been published.

# owner

• Type: String

The user information of the seller.

# seller

• Type: String

The name of the seller of the item.

# attributes

• Type: Object

A Javascript object that contains all the specific attributes of the item. The number of attributes varies depending on the category and the item.

# has_phone

• Type: boolean

true if the seller of the item mentioned her phone number.

# getDetails()

• Return: Promise<Item>

Get the details

await item.getDetails()
item.description

# getPhoneNumber()

• Return: Promise<String>

Get the phone number of the seller. Pay attention that this API has a strict API usage limit. I recommend that this API is only used when a user request it.

const phone = await item.getPhoneNumber()

# Regions

The ID and Region can be used in the function setRegion to filter the search.

# Departments

The ID and Department can be used in the function setDepartment to filter the search.

# Categories

The ID and Category can be used in the function setCategory to filter the search.