Definición de métodos

Transcripción

1 YIELD-API Definición de métodos 1 / 26

2 Introducción El presente documento describe la interfaz YIELD API, un conjunto de funcionalidades ofrecidas por Incubio para acceder a los datos existentes en su plataforma de Big Data YIELD. YIELD API ofrece un subconjunto de las funcionalidades y los datos totales de YIELD, de manera que esta documentación no incluye todos los métodos y funciones disponibles en YIELD. En resumen, YIELD API ofrece las siguientes funcionalidades: Consulta de los datos de un lugar (place) por su identificador Recuperación de imágenes y vídeos relacionados con un lugar (place) Obtención de las interacciones sociales relacionadas con un lugar (place) Búsqueda de lugares (places) por texto libre Obtención de los lugares (places) mejor valorados en una ciudad Consulta de lugares (places) de una ciudad por categorías y subcategorías Consulta de los datos de una empresa (company) por su identificador Recuperación de imágenes y vídeos relacionados con una empresa (company) Búsqueda de empresas (companies) por texto libre Obtención de las empresas (companies) de una determinada categoría Conceptos generales Content types Para facilitar el uso de YIELD API, se deberán enviar las siguientes cabeceras en todas las peticiones: H "Accept: application/json" H "Content Type: application/json" En PHP, dichas cabeceras se pueden enviar de la siguiente manera: curl_setopt($ch, CURLOPT_HTTPHEADER, array('content Type: application/json')); Autenticación 2 / 26

3 YIELD API es un servicio de acceso restringido y controlado. Para su uso, los participantes en la Hackaton deberán solicitar acceso a este servicio enviando un correo electrónico a la dirección yield api@incubio.com con el asunto YIELD API antes de iniciar la hackaton. Una vez creado su usuario, les serán notificados sus datos de acceso respondiendo al mismo correo electrónico con la suficiente antelación. Todas las peticiones a YIELD API deberán incluir una cabecera de autenticación siguiendo el siguiente esquema (en PHP): curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ); curl_setopt($ch, CURLOPT_USERPWD, $COMPANY_NAME.":".$COMPANY_PASSWORD); Donde $COMPANY_NAME y $COMPANY_PASSWORD serán los datos de acceso proporcionados para cada equipo de la hackathon que lo requiera. En términos de la línea de comandos, la petición debe ser como la siguiente: curl i H "Accept: application/json" H "Content Type: application/json" H "Authorization: Basic XXXXXX" X METHOD api.incubio.com/path Donde XXXXXX debe tener por valor base64(company_name:company_password) Casos de Uso Dado que YIELD API ofrece únicamente métodos de consulta y que el sistema ofrece siempre la misma interacción con el usuario, se muestra únicamente un caso de uso que sirve como plantilla para los demás. Consulta al sistema Caso de uso Actores Descripción Obtención de datos de sistema Usuario Obtención de los datos básicos de un lugar (place) 3 / 26

4 Precondiciones Postcondiciones El usuario está autorizado para acceder a YIELD API El usuario obtiene la información solicitada Flujo principal 1. El usuario ejecuta una consulta contra el sistema 2. El sistema valida que el usuario tenga permisos para acceder a la información 3. El sistema valida que los parámetros obligatorios tengan valor 4. El sistema valida que el formato de todos los parámetros 5. El sistema retorna al usuario la información solicitada Alternativas 2. El usuario no tiene acceso al sistema. Se retorna un código de error indicando este hecho. 3. Los parámetros obligatorios no tienen valor. Se retorna un error 404 al usuario 4. Alguno de los parámetros no tiene el formato correcto. Se retorna un error al usuario indicando este hecho. 4 / 26

5 Places API 1. Places El endpoint de Places permite a los usuarios consultar los datos de un lugar determinado por su identificador a. /place/:id Recupera la información básica de un lugar. Método: HTTP GET Parámetros: Nombre del parámetro placeid Descripción Identificador de un lugar (place) Plantilla: api.incubio.com/place/:placeid Ejemplo: api.incubio.com/place/12345 Respuesta: "version" : 1.0, "status" : "ok", "result" : "placeid" : 12345, "name" : "Incubio", "location": "adress" : "Carrer dels Almogàvers 165, Barcelona, España", "city": "Barcelona" "location" : "lat" : , "lon": , 5 / 26

6 "score": 9, "category": "Company", "subcategory": "Incubator", "socialinteractions": 12345, "image": " content/uploads/2013/05/home office.png", "daily": "monday" : "morning": 0.14, "midday": 0.38, "evening": 0.2, "night": 0.1, "latenight": 0.08, "tuesday" : "morning": 1, "midday": 0.5, "evening": 0.4, "night": 0.3, "latenight": 0.2, "wednesday" : "morning": 0.6, "midday": 0.8, "evening": 0.4, "night": 0.3, "latenight": 0.3, "thursday" : "morning": 0.58, "midday": 0.56, "evening": 0.12, "night": 0.3, "latenight": 0.2, "friday" : "morning": 0.65, "midday": 0.68, "evening": 0.21, "night": 0.18, "latenight": 0.1, "saturday" : "morning": 0.1, "midday": 0.07, "evening": 0.02, "night": 0.01, "latenight": 0.01, "sunday" : "morning": 0.1, "midday": 0.1, "evening": 0.1, "night": 0.08, "latenight": / 26

7 b. /place/:id/media Retorna todas las imágenes y videos de un lugar específico. Método: HTTP GET Parámetros: Nombre del parámetro placeid Descripción Identificador de un lugar (place) Plantilla: api.incubio.com/place/:placeid/media Ejemplo: api.incubio.com/place/12345/media Respuesta: "version" : 1.0, "status" : "ok", "result" : "placeid" : 12345, "images": [ " content/uploads/2013/05/home office.png", " startups.com/media/startups/ /images/ofi 1_1.JPG" " " " " "videos": [ " " ] 7 / 26

8 c. /place/:id/interactions Retorna una lista de todas las interacciones sociales disponibles, relacionadas con un lugar (place) específico. Método: HTTP GET Parámetros: Nombre del parámetro placeid source from to Descripción Identificador de un lugar (place) Social network: twitter, facebook, instagram... Fecha/hora de inicio Fecha/hora de final Plantilla: api.incubio.com/place/:placeid/interactions?source=[source]&from=[from_dat e]&to=[to_date] Ejemplo: api.incubio.com/place/12345/interactions?source=twitter&from= &to= Respuesta: 8 / 26

9 "version" : 1.0, "status" : "ok", "result" : "twitter" : [ "contributors": null, "coordinates": "coordinates": [ , "type": "Point", "created_at": "Mon Jun 23 09:17: ", "entities": "hashtags": [ "symbols": [ "trends": [ "urls": [ "user_mentions": [ "id": , "id_str": " ", "indices": [ 20, 28 "name": "Incubio", "screen_name": "incubio" ], "favorite_count": 0, "favorited": false, "filter_level": "medium", "geo": "coordinates": [ , "type": "Point", "id": , "id_str": " ", "in_reply_to_screen_name": null, "in_reply_to_status_id": null, "in_reply_to_status_id_str": null, "in_reply_to_user_id": null, "in_reply_to_user_id_str": null, "lang": "es", "place": "attributes":, "bounding_box": "coordinates": [ [ [ 9 / 26

10 [ [ [ ] , , , , ] "type": "Polygon", "country": "Espa\u00f1a", "country_code": "ES", "full_name": "Barcelona, Catalonia", "id": "74c8e dd", "name": "Barcelona", "place_type": "city", "url": " "possibly_sensitive": false, "retweet_count": 0, "retweeted": false, "source": "<a href=\" rel=\"nofollow\">twitter for iphone</a>", "text": "Va llegando gente "truncated": false, "user": "contributors_enabled": false, "created_at": "Wed Jun 18 11:19: ", "default_profile": false, "default_profile_image": false, "description": "I was a nerd before it was cool.", "favourites_count": 406, "follow_request_sent": null, "followers_count": 704, "following": null, "friends_count": 749, "geo_enabled": true, "id": , "id_str": " ", "is_translator": false, "lang": "en", "listed_count": 35, "location": "Barcelona", "name": "Pablo Casado", "notifications": null, "profile_background_color": "C0DEED", 10 / 26

11 "profile_background_image_url": " tionx.jpg", "profile_background_image_url_https": " ctionx.jpg", "profile_background_tile": true, "profile_image_url": " "profile_image_url_https": " "profile_link_color": "0084B4", "profile_sidebar_border_color": "C0DEED", "profile_sidebar_fill_color": "DDEEF6", "profile_text_color": "333333", "profile_use_background_image": true, "protected": false, "screen_name": "hardlifeofapo", "statuses_count": 13457, "time_zone": "Madrid", "url": " "utc_offset": 7200, "verified": false "facebook" : [ "instagram" : [ ] 2. Search a. /place/search Retorna una lista de todos los lugares (places) cuyo nombre coincide con el string dado Método: HTTP GET Parámetros: Nombre del parámetro query Descripción Nombre (parcial) del lugar a buscar 11 / 26

12 location radius Coordinadas GPS en el formato lat, lon Distancia en Km Plantilla: api.incubio.com/place/search/[query]?location=[lat,lon]&radius=[distance] Ejemplo: api.incubio.com/place/search/incu?location=[ , ]&radius=2 Respuesta: "results": [ "category": "Company", "daily": "friday": "evening": 0.21, "latenight": 0.1, "midday": 0.68, "morning": 0.65, "night": 0.18, "monday": "evening": 0.2, "latenight": 0.08, "midday": 0.38, "morning": 0.14, "night": 0.1, "saturday": "evening": 0.02, "latenight": 0.01, "midday": 0.07, "morning": 0.1, "night": 0.01, "sunday": "evening": 0.1, "latenight": 0.06, "midday": 0.1, "morning": 0.1, "night": 0.08, "thursday": "evening": 0.12, 12 / 26

13 "latenight": 0.2, "midday": 0.56, "morning": 0.58, "night": 0.3, "tuesday": "evening": 0.4, "latenight": 0.2, "midday": 0.5, "morning": 1, "night": 0.3, "wednesday": "evening": 0.4, "latenight": 0.3, "midday": 0.8, "morning": 0.6, "night": 0.3, "image": " content/uploads/2013/05/home office.png", "location": "location": "lat": , "lon": , "adress": "Carrer dels Almog\u00e0vers 165, Barcelona, Espa\u00f1a" "city": "Barcelona", "name": "Incubio", "placeid": 12345, "score": 9, "socialinteractions": 12345, "subcategory": "Incubator", "url": " "status": "ok", "version": Cities a. /place/city/:cityname/ Retorna una lista de los lugares más recomendados en una ciudad 13 / 26

14 Método: HTTP GET Parámetros: Nombre del parámetro cityname day time Descripción Nombre de la ciudad Día de la semana: 1 = monday, 2 = tuesday... 7 = sunday Momento del día: morning, midday, evening, night, latenight y now son los únicos valores aceptados. Plantilla: api.incubio.com/place/city/[cityname]?day=[dayofweek]&when=[when] Ejemplo: api.incubio.com/place/city/barcelona?day=7&when=latenight Respuesta: 14 / 26

15 "results": [ "placeid": "654235", "name": "Esencia" "category": "Dance club", "subcategory" "Latin dance", "score" : 8, "location" : "location": "lat": , "lon" , "adress": "Carrer d'aribau, 191, Barcelona, Barcelona, Spain" "city": "Barcelona", "image" : " b ams.xx.fbcdn.net/hphotos xap1/t1.0 9/p480x480/ _ _ _n.jpg", "url" : "" "status": "ok", "version": 1.0 b. /place/city/:cityname/:categoryname Método: HTTP GET Parámetros: Nombre del parámetro cityname categoryname Descripción Nombre de la ciudad Nombre de la categoría Plantilla: api.incubio.com/place/city/[cityname]/[categoryname] 15 / 26

16 Ejemplo: api.incubio.com/place/city/barcelona/eating/ Respuesta: "results": [ "category": "eating", "placeid": "85213", "image": " cdn.tripadvisor.com/media/photo s/04/a0/72/71/sopa.jpg", "location": "location": "lat": , "lon": , "adress": "Carrer de Roc Boronat, Barcelona Spain" "city": "Barcelona", "name": "Sopa Barcelona", "score": 6, "subcategory": "vegan", "url": " "status": "ok", "version": Categories a. /place/city/:categoryname/:subcategory Método: HTTP GET Parámetros: Nombre del parámetro cityname categoryname Descripción The name of the city Nombre de la Categoría 16 / 26

17 subcategory Nombre de la Subcategoría Plantilla: api.incubio.com/place/city/cityname/categoryname/[subcategory] Ejemplo: api.incubio.com/place/city/barcelona/eating/american Respuesta: "results": [ "category": "eating", "subcategory": "american", "placeid": "654851", "image": " s5y2gu6zilc/txppka IfII/AAAAAAAAAIw/MhaIuC 2A6s/s1600/CIMG6 681.JPG", "location": "location": "lat": , "lon": , "adress": "Carrer de Pamplona, Barcelona Spain", "city": "Barcelona", "name": "Taberna Sonora", "score": 4, "subcategory": "american", "url": " "status": "ok", "version": / 26

18 Companies API 1. Company El endpoint de empresa (Company) permite a los usuarios obtener datos de una empresa mediante su identificador a. /company/:id Recupera la información básica de una empresa (company) Método: HTTP GET Parámetros: Nombre del parámetro companyid Descripción Identificador de una empresa Plantilla: api.incubio.com/company/:companyid Ejemplo: api.incubio.com/company/twitter Respuesta: "status": "ok", "version": 1.0, "result": "id": "twitter", "blog_feed_url": " "blog_url": " "category_code": "social", "description": "Real time communication platform", " _address": "press@twitter.com", "external_links": [ 18 / 26

19 "external_url": " bin/browse edgar?action=getcompany&cik= ", "title": "SEC", "external_url": " "title": "Twitter in the Community", "external_url": " "title": "Facebook" "founded_date": , "founded_day": 21, "founded_month": 3, "founded_year": 2006, "homepage_url": " "image": "assets/images/resized/0042/6251/426251v1 max 450x450.jpg", "name": "Twitter", "number_of_employees": 1300, "offices": [ "address1": "1355 Market St.", "address2": "", "city": "San Francisco", "country_code": "USA", "description": "", location : "lat": , "lng": , "state_code": "CA", "zip_code": "94103" "overview": "<p>twitter is an online social network and a microblogging service that enables users to send and read \u201ctweets, which are text messages limited to 140 characters. Registered users of Twitter are able to read and post tweets via the web, SMS or mobile applications.</p>\n\n<p>created in March 2006, Twitter is a global real time communications platform with 400 million monthly visitors to twitter.com and more than <a href=\" passes 200m monthly active users a 42 i ncrease over 9 months/\" title=\"200 million monthly active users\">200 million monthly active users</a> around the world. It receives a billion tweets every 2.5 days on every conceivable topic. World leaders, major athletes, star performers, news organizations and entertainment outlets are among the millions of active Twitter accounts through which users can truly get the pulse of the planet.</p>\n\n<p>twitter is based in San Francisco and has offices in New York City, Boston, San Antonio and Detroit. It was founded by <a href=\"/person/jack dorsey\" title=\"jack Dorsey\" rel=\"nofollow\">jack Dorsey</a>, <a href=\"/person/evan williams\" title=\"evan Williams\" rel=\"nofollow\">evan Williams</a>, <a href=\"/person/biz stone\" title=\"biz Stone\" rel=\"nofollow\">biz Stone</a> and <a href=\"/person/noah glass 3\" title=\"noah Glass\" rel=\"nofollow\">noah Glass</a></p>", "permalink": "twitter", "phone_number": "", "products": [ 19 / 26

20 , "name": "Twitter Blocks", "permalink": "twitter blocks" "name": "Twicco", "permalink": "twicco" "tag_list": "text, messaging, social, community, twitter, tweet, twttr, microblog, sms", "twitter_username": "twitter", "video_embeds": [ "description": "<p>twitter for Small Business</p>", "embed_code": "<iframe width=\"430\" height=\"242\" src=\" frameborder=\"0\" allowfullscreen></iframe>" ] b. /company/:id/media Retorna todas las imágenes y todos los vídeos disponibles, relacionados con una empresa dada Método: HTTP GET Parámetros: Nombre del parámetro companyid Descripción Identificador de una empresa Plantilla: api.incubio.com/company/:companyid/media Ejemplo: api.incubio.com/company/facebook/media 20 / 26

21 Respuesta: "version" : 1.0, "status" : "ok", "result" : "companyid" : "facebook", "images": [ "assets/images/resized/0004/2816/42816v1 max 450x450.png" "videos": [] 2. Search a. /company/search Retorna una lista de las empresas (companies) cuyo nombre coincide con el string indicado Método: HTTP GET Parámetros: Nombre del parámetro query location radius Descripción Cadena de búsqueda Coordenadas GPS en el formato lat, lon Distancia en Km Plantilla: api.incubio.com/company/search/[query]?location=[lat,lon]&radius=[distance ] Ejemplo: api.incubio.com/company/search/media 21 / 26

22 Respuesta: "status": "ok", "version": 1.0, "results": [ "blog_feed_url": null, "blog_url": null, "category_code": null, "description": null, " _address": null, "external_links": [ "founded_date": , "founded_day": null, "founded_month": null, "founded_year": null, "homepage_url": null, "id": "abril media", "image": null, "name": "Abril Media", "number_of_employees": null, "offices": [ "overview": null, "partners": [ "permalink": "abril media", "products": [ "tag_list": null, "twitter_username": null, "blog_feed_url": "", "blog_url": " "category_code": "software", "description": "Website Design Delhi Addictive Media, w", " _address": "albertson.seo@gmail.com", "external_links": [ "external_url": " "title": "Website Design Delhi, Website Design Company Delhi" "founded_date": , "founded_day": 1, "founded_month": 8, "founded_year": 2009, "homepage_url": " "id": "addictive media", "image": null, "name": "Addictive Media", "number_of_employees": 7, "offices": [ 22 / 26

23 "overview": "<p>addictive Media is a full service graphic design agency. We offer services for branding, web, interactive, print, programming, and multimedia presentation.</p>\n\n<p>at Addictive Media, we strive to be the front runner in innovation and creativity in web designing and development. As a creative agency we translate website development expertise into value for our clients through our well researched skills, web design consulting and website designing solutions, that also includes brand development, e commerce solutions, search engine marketing and multimedia presentations.</p>\n\n<p>we as a creative agency understand the importance of our client\u00e2\u20ac\u2122s requirements and its influence on the best desired output. We work closely with our clients to help them decide and define their exact requirements. Our brainstorming sessions are geared to understand our clients better and translate their dream website into reality.</p>\n\n<p>we ensure that our services enable our clients to create a brand, optimize existing systems, save operational costs and sell better. We believe in delivering the best possible results for each of our clients. Addictive Media ensures that the quality of the work delivered exceeds the expectations of customers. A convenient, clear and consistent client communication is the focal point of our successful customer contact programs.</p>\n\n<p>the fundamental principle of our company is customer satisfaction. Addictive Media works closely with your organization to develop a web site that is consistent with the history of your company and at the same time competent with today\u00e2\u20ac\u2122s technology. We provide the kind of web site that keeps your customers satisfied, so that they keep coming back for more. Our custom designs are affordable for every budget.</p>\n\n<p>addictive Media provides the highest standards in support and service. We are committed to efficiency and flexibility when it comes to delivering end results. We promise cost effective, timely, inspirational and quality solutions that add significant value to your enterprise. All our team members are experts in their particular field who will deliver a website that captures the requirements of your company, the attention of your target audience and has an edge over competitor websites.</p>\n\n<p>feel free to go through our available services and portfolio. You can contact us for a free estimate. We look forward to delivering you a refreshing web site that is totally compatible with the characteristics and principles of your company.\nweb hosting Hosting Reviewed gives you a glimpse of the best web hosts available when it comes to affordable web hosting. Backed with customer reviews, the site will help you decide which web host is the right one for you.</p>", "permalink": "addictive media", "phone_number": " ", "products": [ "tag_list": "website design delhi, web design delhi, website design company delhi, seo company delhi, seo services company delhi, search engine optimization", "twitter_username": "Addictivemedia", ] 3. Categories a. /company/category Retorna una lista de las empresas (companies) de una categoría específica 23 / 26

24 Método: HTTP GET Parámetros: Nombre del parámetro category location radius Descripción Cadena de búsqueda Coordenadas GPS en el formato lat, long Distancia en Km Plantilla: api.incubio.com/company/category/[category]?location=[lat,lon]&radius=[dis tance] Ejemplo: api.incubio.com/company/category/social Respuesta: "results": [ "blog_feed_url": "", "blog_url": "", "category_code": "social", "description": "", " _address": "contato@aatag.com", "external_links": [ "founded_date": , "founded_day": 1, "founded_month": 6, "founded_year": 2010, "homepage_url": " "id": "aatag", "image": "assets/images/resized/0009/1254/91254v4 max 450x450.png", "name": "aatag", "number_of_employees": 4, "offices": [ 24 / 26

25 "address1": "Liverdade Avenue, 1701", "address2": "", "city": "Sorocaba", "country_code": "BRA", "description": "aatag Office", location : "lat": , "lng": , "state_code": null, "zip_code": " " "overview": "<p>our goal at aatag is to give everyone the ability to easily access services and objects customized for their profile, context, preferences, social graph and stream.</p>\n\n<p>aatag created a platform where user sign up once and can use their profile, preference, context, social graph and stream n times. User gives micro permissions each time they interact.</p>\n\n<p>an example of a service: aatag here and send flowers to your wife \u009d. The end user waves his rfid card or sticker over the board and our platform access his profile in Facebook, check who his wife is and send to her an or Facebook message saying: Hi Patrizia, I am in Walmart Sorocaba and when I saw these flowers my heart remembered you, xxx Augusto </p>\n\n<p>we use rfid to create a completely new experience for end users giving micro permissions and receive personalized services and products. aatag is an ubiquitous platform in the real world where the user do not need to carry a device with keyboard, camera, screen, batteries, network, mouse or touch to interact with services and products. </p>\n\n<p>we created an open platform for Internet of Things. We took care of connecting and giving tags to the end user and created a couple of services (APIs) to let other services providers interact with the user profile, preferences, context, social graph and stream.</p>", "permalink": "aatag", "phone_number": "", "products": [ "tag_list": "contactless payment, information exchange, rfid ", "twitter_username": "aatagrfid", "blog_feed_url": "", "blog_url": "", "category_code": "social", "crunchbase_url": " "description": "Alumni Networking. Redefined", " _address": "", "external_links": [ "founded_date": , "founded_day": null, "founded_month": null, "founded_year": null, "homepage_url": " "id": "alumnize", "image": "assets/images/resized/0021/4347/214347v2 max 450x450.jpg", "name": "Alumnize", "number_of_employees": 10, "offices": [ "overview": "<p>whether you are looking for a job, looking to recruit or looking for ways to enhance professional and personal development, Alumnize offers a 25 / 26

26 platform to network with your alumni to achieve your goals</p>\n\n<p>leverage the Power of Alumni network!! Start Alumnizing!</p>", "permalink": "alumnize", "phone_number": "", "products": [ "tag_list": "alumni networking, alumni, college, networking, alumnize", "twitter_username": "alumnize", "status": "ok", "version": / 26