| 
View
 

Metwit API

Page history last edited by Metwit 12 years, 7 months ago

 

clowdy Metwit API

 

The Metwit API allows developers to stream social realtime weather data on their app from Metwit and post weather related content on Metwit platform.

 

Why Social Realtime Weather?

In many geographies weather change frequently in time and across short distance. Social weather data add value to mainstream information we usually and passively get from standard forecasts (i.e. mathematical models predictions) for our everyday life and outdoor activities (such as sports).

 

Example: Brian as a Kitesurfer wants to know the wind status on his favorite beaches. He checks many resources that can tell him the expected wind. Of course he does not want to pick the car, get to the beach and have his day-off spoiled by a wrong forecast. Wouldn't be cool to always have a fellow kitesurfer that can report how are the real weather conditions from the beach?

 

Example: Having barbecue is great! Bob invited all his friend to his barbecue in his garden. The weather looks nice but 20km away a quick storm is about to start and probably it will reach out Bob's House! What if a friend could warn him about the upcoming storm so that you can move all the hosts and the party inside the house?

These common stories show that real time weather is a valuable resource to be consumed with forecast for logn term planning and even standalone for everyday life.

 

Ok, but why should I embed this information on my app?

Weather is a crucial piece of information that can drive additional traffic and improve usage and interaction of every geobased and outdoor content based application.

Our API can be integrated into your "next Sport nieche application" to provide additional context related information and receive geobased alerts on weather. Interactive widgets can be built to stream social targeted weather content directly on blogs and local business websites where their audience can interact with them and share with peers and groups.

 

Check out first list of ideas that one can develop with Metwit API @ hackitaly

 

How does it works?

Working with Metwit's API is easy! The architecture of the API is 100% REST and built for dummies!

 

Getting Started

 

BASE URL = https://api.metwit.me/v2/

 

Authentications

# Definitions

 

- access_token: a token that MUST be sent with every API request

- api_key: the key given to the app developer to authenticate its application; this is an access token

- bearer_token: an access token authorized to do stuff in behalf of an user

 

# Example request

 

Given an access_token = 'abcde123'

 

    GET /v2/sumthing/

    Authorization: Bearer abcde123

 

# Request with api_key

 

A developer gets its api_key = '5a054c8d3c433a0056098bee2156d75710ba9621'

 

    GET /v2/metags/

    Authorization: Bearer 5a054c8d3c433a0056098bee2156d75710ba9621

 

# Get a bearer token

 

I want my app to authenticate an user 'pippo'

 

    POST /v2/auth/

    Authorization: Bearer 5a054c8d3c433a0056098bee2156d75710ba9621

    Content-type: application/json

 

    { "username": "pippo", "password": "paperino" }

 

A typical response will be something like:

 

    HTTP/1.1 200 OK

 

    { "bearer_token": "NUOOdwhH-xKI6bkZSrAh3OWtOeHPHd3ON92tNOetPfG3ntteene-e9dG2vettQ==" }

 

# Use the bearer token

 

I have obtained a bearer_token for my app and an user

 

    POST /v2/metags/

    Authorization: Bearer NUOOdwhH-xKI6bkZSrAh3OWtOeHPHd3ON92tNOetPfG3ntteene-e9dG2vettQ==

 

    { "weather": { "status": "clear" }, "geo": { "lng": 12.42792, "lat": 45.56441 }}

 

Core 

Metwit core interactions allow users to:

  1. report weather condition in a specific location.
  2. explore the weather reported by other users on maps and feeds and interact with them
  3. send and receive notifications on weather conditions and interactions

 

The basic elements of Metwit API Structure are Objects and Resources

An Object is the atomic element used in metwit API. Every field contained into an Object has 3 parameters:

 

Flag
Describe the kind of treatment demanded by the API for the object
Type
Describe the field Object Type
Documentation
A description of the field

 

Object are conventionally written with a starting capital letter. The one used in Metwit API are: User, Metag, Reply, Thank, Notification, Story.

 

A Resource is a collection of Object. Metwit API can perform REST Actions over resources. Resources in Metwit are written in smaller case and are: users, metags, replies, thanks, notification, stories.

 

Resources

 

users

users is a collections of objects called User.

 

A User is an object with the following fieds:

Name Flag Type Description
id guaranteed string unique identifier for the User object
nickname guaranteed string the display name for the user
metags_count guaranteed number he number of metags this user has sent
today_metags_count guaranteed number the numbers of metags this user has sent during the last day
avatar guaranteed string the url of the avatar image for this user
is_followed guaranteed boolean whether the current user follows this user
followers_count guaranteed number the number of users who follow this user
following_count guaranteed number the number of users this user follows
has_facebook guaranteed boolean whether this user has connected its account to Facebook
has_twitter guaranteed boolean whether this user has connected its account to Twitter
email private string the email address of this user

 

Action allowed on the user resource are

Action Description
 
 
GET /<ID>/ Get the single user with that / <ID>/
 
 
PATCH /<ID>/ Edit a single user with that / <ID>/
 
 
PUT /<ID>/ Replace a user with that / <ID>/

 

metags

metags is a collection of objects called Metag

 

Users reports are object called Metag. A Metag is a symbolic description of the current weather condition on a specific location. Metag fields are

Name Flag Type Description
id guaranteed string unique identifier for the User object
timestamp guaranteed timestamp the display name for the user
weather mandatory,guaranteed Weather ????
geo mandatory,guaranteed GeoJSON the location of the Metag (this is always a Point)
user guaranteed User the user performing the metag
comment optional string the user performing the metag
photo optional string the url of the photo posted with this Metag
replies_count guaranteed number the number of replies attached to this Metag
thanks_count guaranteed number the number of Users who thanked for this Metag

 

 

Weather is an object with the following fields:

Name Flag Type Description
status guaranteed,mandatory weather weather status reported by the user
measured optional Measured the measured data attached to a weather report
felted optional Felt the perceived feel of the weather attached to a weather report

 

weather is one of the following string

String Icon Description
unknown none nil weather status
clear The sky is clear (sun or Moon clearly visible)
rainy Rain is falling down from the sky
stormy There is a storm going on with thunder and lightning
snowy Sonw is falling down (if snow is on the ground and it's not snowing the weather isn't snowy)
partly cloudy There are clouds in the sky but sun or moon are visible
cloudy There are a lot of clouds covering sun or moon
hailing Hail is falling down
heavy seas Sea with consistent waves, enough for surfing
calm seas Flat or almost flat sea.. great for swimming
foggy Foggy weather
snow flurries Snow mixed to water is falling down or light snow transported by wind
windy The wind is enough to enjoy sailing or ktesufing

 

Measured is an object with the following fields:

Name Flag Type Description
temperature optional number the measured air temperature (in K)
wind_chill optional number the measured wind chill temperature (in K)
humidity optional number the measured relative humidity (in %)
dew_point optional number the measured dew point (in K)
visibility optional number the measured visibility (in m)
wind_speed optional number the measured wind speed (in m/s)
wind_direction optional number the measured wind direction (in degrees, 0°=N, 90°=E, 180°=S, 270°=W)
pressure optional number the measured atmospheric sea-level pressure (in hPa)
rainfall optional number the measured rain precipitation (in mm/hour)
snowall optional number the measured snow precipitation (in cm/hour)

 

Felt is an object with the following fields:

Name Flag Type Description
temperature guaranteed,mandatory number a measure of the felt temperature on a 0-100 scale (50=fine, 0=extremely cold, 100=extremely hot)
intensity optional number a measure of the perceived intensity of the reported weather phenomenon (only for sunny, rainy, stormy, snowy, cloudy, hailing, heavy seas) on a 0-100 scale (0=almost imperceivable, 50=moderate, 100=extreme)
visibility optional number a measure of the perceived visibility on a 0-100 scale (0=perfect, 50=moderate, 100=no visibility)
humidity optional number a measure of the perceived humidity on a 0-100 scale (0=dry, 50=normal, 100=extremely wet); this is a felt measure, not actual relative humidity
wind_intensity optional number a measure of the perceived wind intensity on a 0-100 scale (0=absent, 50=moderate, 100=extreme)

 

Actions allowed on metags resource are:

Supported methods Description
GET Get the list of metags
GET /?rect=lat_n,lon_w,lat_s,lon_e Get metags in that rectangle of coords
GET /<ID>/ Get the single metag with that / <ID>/
POST Add a new metag to the list
DELETE Delete a Metag with that / <ID>/ from the list
PATCH /<ID>/ Edit a single Metag with that / <ID>/
PUT Replace the single Metag with that / <ID>/
/<id>/flag/ Flag a Metag with that /<id>/
/<id>/share/ Flag a Metag with that /<id>/

 

A Metag contains also two important Subresources: replies and thanks.

 

 

replies

replies is a collection of Reply.

 

A Reply is an object associated to a metag with the following fields

Name Flag Type Description
Id guaranteed string unique identifier for the Reply object
text guaranteed string text of the reply
user guaranteed User ?
timestamp guaranteed timestamp the time at which the Reply was issued

 

On the subresource replies The following actions are allowed:

Actions Description
GET Get the list of reply to a Metag
GET /<ID>/ Get the single Reply with that / <ID>/
POST Add a new reply to a Metag
DELETE /<ID>/ Delete the single Reply with that / <ID>/ from the metag

 

thanks

Thanks is a collection of Thank that a user gives to other users for their tags

 

A Thank is an object associated to a metag. Thanks are issued by a user to a metag. A Thank has the following fields

Name Flag Type Description
? guaranteed string unique identifier for the Reply object

 

Actions allowed on the thanks subresource are:

Actions Description
GET Get the list of thanks to a Metag
POST Add a thank to a Metag
DELETE Delete the single thank from the metag

 

notifications

notifications is a collection of object called Notification

 

A Notification is an object representing an alert. The alert are issued to userA in consequence actions done by userB. Notification fields are:

Name Flag Type Description
Id guaranteed string unique identifier for the Notification object
timestamp guaranteed timestamp the time at which the Notification was issued
type guaranteed, mandatory string an identifier for the type of the Story
picture guaranteed string the url of a picture that represents the Notification
is_read guaranteed bolean whether this notification has already been read
details guaranteed, mandatory dictionary the details of the Notification (see Notification Types)
alt_text guaranteed string a descriptive text for the Notification)

 

Actions allowed on the notifications resource are:

Action Description
GET Get the list of Notifications
GET /<ID>/ Get the single Notification with that / <ID>/
POST Add a new Notification to the list
PATCH /<ID>/ Edit a single Notification with that / <ID>/

 

stories

stories is a collection of object called Story

 

A Story is an object representing content that ends up in your peers that are following you. Story as the following fields:

Name Flag Type Description
Id guaranteed string unique identifier for the Story object
timestamp guaranteed timestamp the time at which the Story was issued
type guaranteed, mandatory string an identifier for the type of the Story
picture guaranteed string the url of a picture that represents the Story
user guaranteed User the user who originated the Story
details guaranteed, mandatory dictionary the details of the Notification (see Story Types)
alt_text guaranteed string a descriptive text for the Notification

 

Actions allowed on the stories resource are:

Actions Description
GET Get the list of Story in the collection
GET /<ID>/ Get the single Story with that / <ID>/
POST Add a new Story to the list

 

Comments (0)

You don't have permission to comment on this page.