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:
- report weather condition in a specific location.
- explore the weather reported by other users on maps and feeds and interact with them
- 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 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.