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лв./л"
}
]
}