Application Programming Interface

кратка документация на API-то на Fuelo


Въведение:

Fuelo API дава достъп за четене до базата данни от цени и бензиностанции на сайта fuelo.net. Ако смятате, че има грешка в данните или искате да добавите нови, трябва да се свъжете с нас - това може да направите с формата за контакти или на e-mail support at fuelo.net

Ключ за достъп:

За да изпълнявате заявки към нашето API, ще ви е необходим ключ за достъп или просто "key". Може да получите ключ, от страницата за заявка. Ключът е безплатен.

Ограничения:

Ключът е само за четене. За сега не се предвижда възможност за промяна на данните чрез API.
Всеки ключ има ограничение от 5000 заявки на ден. Сгрешените заявки също се броят. Ако имате нужда от повече заявки - свържете се с нас.


PRICE

Връща средната цена за страната по тип гориво и дата
HTTP заявка : GET
URL: http://fuelo.net/api/price

Заявка

заявката се изпраща като стандартни GET параметри
Параметър Пример Описание
key * XXXXXXXXXXXXXXX Вашият ключ за достъп до базата на fuelo. Състои се от 15 символа (букви и цифри). Ако все още нямате ключ, заявете вашия.
fuel * gasoline Eдин от следните типове гориво: gasoline, diesel, lpg или methane.
date 2013-09-15 Датата за която желаете средна цена на горивото във формат ГГГГ-ММ-ДД. Ако не е посочена, се взема текущия ден.
Параметрите отбелязани със звездичка (*) са задължителни !

Отговор

отговорът е JSON кодиран масив
Параметър Пример Описание
status * OK Статуса на върнатия отговор - "OK" ако заявката е минала успешно или "error" при грешка.
error_message you must specify fuel type При статус "error", съобщение каква точно е грешката. При статус "ОК", това поле липсва.
fuel gasoline Типът гориво поискан в заявката.
date 2013-09-15 Датата поискана в заявката във формат ГГГГ-ММ-ДД.
price 2.61 Средна цена на желаното гориво за зададения ден.
dimension лв./л Дименсията на цената - за бензин, дизел и газ е "лв./л", за метан е "лв./кг".
Параметрите отбелязани със звездичка (*) присъстват винаги, останалите не са задължителни !

Пример:

Заявка:
http://fuelo.net/api/price?key=XXXXXXXXXXXXXXX&fuel=gasoline&date=2013-09-16

Отговор:
{
    "status":"OK",
    "fuel":"gasoline",
    "price":2.61,
    "dimension":"лв./л",
    "date":"2013-09-16"
}


GASSTATION

Връща подробна информация за дадена бензиностанция
HTTP заявка : GET
URL: http://fuelo.net/api/gasstation

Заявка

заявката се изпраща като стандартни GET параметри
Параметър Пример Описание
key * XXXXXXXXXXXXXXX Вашият ключ за достъп до базата на fuelo. Състои се от 15 символа (букви и цифри). Ако все още нямате ключ, заявете вашия.
id * 1 Идентификационен номер на бензиностанцията в нашата база. Може да се намери от URL адреса в сайта или чрез API заявка gasstations.
Параметрите отбелязани със звездичка (*) са задължителни !

Отговор

отговорът е JSON кодиран масив
Параметър Пример Описание
status * OK Статуса на върнатия отговор - "OK" ако заявката е минала успешно или "error" при грешка.
error_message you must specify gasstation id При статус "error", съобщение каква точно е грешката. При статус "ОК", това поле липсва.
id 256 Иденатификационен номер на обекта в нашата база данни.
lat 43.2228 Географската ширина на обекта.
lon 27.8711 Географската дължина на обекта.
Параметрите отбелязани със звездичка (*) присъстват винаги, останалите не са задължителни или може да са празни!

Пример:

Заявка:
http://fuelo.net/api/gasstation?key=XXXXXXXXXXXXXXX&id=256

Отговор:
{
    "status":"OK",
    "id":"256",
    "lat":"43.2228",
    "lon":"27.8711",
    "brand_name":"Eko",
    "brand_id":"1",
    "name":"Варна - Варненчик",
    "city":"Варна",
    "address":"бул. Владислав Варненчик",
    "zip":"9009",
    "phone":"0896754523",
    "worktime":"0-24 ч.",
    "services":"мини маркет, кафе-бар",
    "payments":"в брой, Visa, MasterCard, BRS, AMEX, Карти ЕКО",
    "foursquare_id":"4e0d9e6baeb7a5b33ee13ee0",
    "wikimapia_id":"17465643"
}


GASSTATIONS

Връща списък от бензиностанции филтрирани по критерии
HTTP заявка : GET
URL: http://fuelo.net/api/gasstations

Заявка

заявката се изпраща като стандартни GET параметри
Параметър Пример Описание
key * XXXXXXXXXXXXXXX Вашият ключ за достъп до базата на fuelo. Състои се от 15 символа (букви и цифри). Ако все още нямате ключ, заявете вашия.
brand_id 1 Идентификационен номер на марката в нашата база. Може да се намери от URL адреса в сайта или чрез API заявка.
fuel lpg Горивото, което задължително трябва да се предлага в бензиностанциите. Eдин от следните типове: gasoline, diesel, lpg или methane.
limit 50 Максималния брой бензиностанции, които да бъдат върнати от заявката. При липса на този параметър, по подразбиране се приема 1000 обекта.
offset 100 Отклонението от първия резултат. Удобно при странициране. При липса на този параметър, по подразбиране се приема 0.
Параметрите отбелязани със звездичка (*) са задължителни !

Отговор

отговорът е JSON кодиран масив
Параметър Пример Описание
status * OK Статуса на върнатия отговор - "OK" ако заявката е минала успешно или "error" при грешка.
error_message you must specify gasstation id При статус "error", съобщение каква точно е грешката. При статус "ОК", това поле липсва.
num_all_results 1004 Общия брой намерени бензиностанции, отговарящи на критериите, без да се съобразява параметъра limit.
num_results 1000 Броя върнати резултати в масива gasstations.
gasstations [ ] Масив от безиностанции с кратка информация за тях.
Параметрите отбелязани със звездичка (*) присъстват винаги, останалите не са задължителни или може да са празни!

Пример:

Заявка:
http://fuelo.net/api/gasstations?key=XXXXXXXXXXXXXXX&brand_id=8&fuel=lpg

Отговор:
{
    "status":"OK",
    "num_all_results":2,
    "num_results":2,
    "gasstations":
    [
        {
            "id":"1459",
            "lat":"43.5677",
            "lon":"27.8536",
            "brand_name":"Атанасов груп",
            "brand_id":"8",
            "name":"Добруджа 2",
            "city":"Добрич",
            "address":"бул. Добруджа №2"
        },
        {
            "id":"1460",
            "lat":"43.567",
            "lon":"27.8468",
            "brand_name":"Атанасов груп",
            "brand_id":"8",
            "name":"Дружба 1",
            "city":"Добрич",
            "address":"бул. Добруджа"
        }
    ]
}


NEAR

Връща списък от бензиностанции, по зададени географски координати
HTTP заявка : GET
URL: http://fuelo.net/api/near

Заявка

заявката се изпраща като стандартни GET параметри
Параметър Пример Описание
key * XXXXXXXXXXXXXXX Вашият ключ за достъп до базата на fuelo. Състои се от 15 символа (букви и цифри). Ако все още нямате ключ, заявете вашия.
lat * 42.683 Географската ширина около която ще се търси.
lon * 23.317 Географската дължина около която ще се търси.
fuel lpg Горивото, което задължително трябва да се предлага в бензиностанциите. Eдин от следните типове: gasoline, diesel, lpg или methane.
limit 50 Максималния брой бензиностанции, които да бъдат върнати от заявката. При липса на този параметър, по подразбиране се приема 100 обекта. Максималната стойност е 100.
distance 100 Радиус в километри, в който да се търси. При липса на този параметър, по подразбиране се приема 100 километра. Максималната стойност е 100.
Параметрите отбелязани със звездичка (*) са задължителни !

Отговор

отговорът е JSON кодиран масив
Параметър Пример Описание
status * OK Статуса на върнатия отговор - "OK" ако заявката е минала успешно или "error" при грешка.
error_message you must provide lat and lon При статус "error", съобщение каква точно е грешката. При статус "ОК", това поле липсва.
lat 42.683 Географската ширина около която се търси.
lon 23.317 Географската дължина около която се търси.
fuel lpg Горивото, което задължително трябва да се предлага в бензиностанциите. Това поле присъства, само ако е зададено в заявката
num_results 100 Броя върнати резултати в масива gasstations.
gasstations [ ] Масив от безиностанции с кратка информация за тях.
Параметрите отбелязани със звездичка (*) присъстват винаги, останалите не са задължителни или може да са празни!

Пример:

Заявка:
http://fuelo.net/api/near?key=XXXXXXXXXXXXXXX&lat=42.683&lon=23.317&limit=3&distance=10&fuel=lpg

Отговор:
{
    "status":"OK",
    "lat":42.683,
    "lon":23.317,
    "distance":10,
    "limit":3,
    "num_results":3,
    "gasstations":
    [
        {
            "id":"272",
            "lat":"42.6807",
            "lon":"23.3084",
            "brand_name":"Eko",
            "brand_id":"1",
            "name":"София - България",
            "city":"София",
            "address":"бул. България и ул. Д-р Стефан Сарафов",
            "distance":"0.7481851198384948"
        },
        {
            "id":"1290",
            "lat":"42.6666",
            "lon":"23.324",
            "brand_name":"Petrol",
            "brand_id":"6",
            "name":"7122",
            "city":"София",
            "address":"бул. Вапцаров (до Ехро 2000)",
            "distance":"1.9113423836896142"
        },
        {
            "id":"208",
            "lat":"42.6681",
            "lon":"23.3289",
            "brand_name":"Eko",
            "brand_id":"1",
            "name":"София - Вапцаров",
            "city":"София",
            "address":"бул. Никола Вапцаров №2А",
            "distance":"1.9214277066215255"
        }
    ],
    "fuel":"lpg"
}


NEWS

Връща последните елементи от секцията "Новини" в сайта
HTTP заявка : GET
URL: http://fuelo.net/api/news

Заявка

заявката се изпраща като стандартни GET параметри
Параметър Пример Описание
key * XXXXXXXXXXXXXXX Вашият ключ за достъп до базата на fuelo. Състои се от 15 символа (букви и цифри). Ако все още нямате ключ, заявете вашия.
count 20 Броя новини, които да се покажат. По подразбиране се приема 10. Максималната стойност е 100.
brand 1 Идентификационен номер на марката в нашата база, за която трябва да се отнася новината. Може да се намери от URL адреса в сайта или чрез API заявка.
fuel lpg Горивото, за което задължително трябва да се отнася новината. Eдин от следните типове: gasoline, diesel, lpg или methane.
Параметрите отбелязани със звездичка (*) са задължителни !

Отговор

отговорът е JSON кодиран масив
Параметър Пример Описание
status * OK Статуса на върнатия отговор - "OK" ако заявката е минала успешно или "error" при грешка.
error_message no news found. check filters При статус "error", съобщение каква точно е грешката. При статус "ОК", това поле липсва.
news [ ] Масив с новините. Вижте примера.
Параметрите отбелязани със звездичка (*) присъстват винаги, останалите не са задължителни или може да са празни!

Пример:

Заявка:
http://fuelo.net/api/news?key=XXXXXXXXXXXXXXX&count=4&fuel=lpg

Отговор:
{
    "status":"OK",
    "news":[
        {
            "id":"1275",
            "date":"2014-05-28 09:00:09",
            "type":"fuel",
            "brand":null,
            "fuel":"lpg",
            "text":"Пропан-бутанът поскъпна средно с 3ст. до 1,16лв./л"
        },
        {
            "id":"1272",
            "date":"2014-05-28 08:00:01",
            "type":"brand",
            "brand":"4",
            "fuel":"lpg",
            "text":"Rompetrol Автогаз поевтиня с 3ст. до 1,14лв./л"
        },
        {
            "id":"1267",
            "date":"2014-05-28 07:00:01",
            "type":"brand",
            "brand":"1",
            "fuel":"lpg",
            "text":"Eko Пропан Бутан поскъпна с 10ст. до 1,17лв./л"
        },
        {
            "id":"1268",
            "date":"2014-05-28 07:00:01",
            "type":"brand",
            "brand":"3",
            "fuel":"lpg",
            "text":"OMV Пропан Бутан поскъпна с 10ст. до 1,17лв./л"
        }
    ]
}