REST API MGID for publishers

The main provisions of REST API

REST API allows you to integrate external applications with Mgid online  
advertising system.
API provides the ability to retrieve, add, and modify the data. Practically each  object in Mgid (whether it's a client, an advertising company, a teaser, etc.) can  be controlled by API. Mgid REST API Request is an HTTP request, which, with  the help of the ways in URL the object to perform the action is specified, and  with the help of parameters the necessary data is passed. Mgid API is a "RESTful  Web API". The API uses the following REST commands:
● GET
● PUT
● PATCH
● POST
● DELETE

The query parameters are case sensitive.

These commands correspond to certain actions within the Mgid system. Get an item or a collection of items (for example, a list of advertising campaigns):    

Command Action Description
POST Create Creates a new element (eg, a teaser)
GET Get (read)    Retrieve an element or a collection of elements
PUT Update Recreate an existing element or a collection of elements
PATCH Change Change certain properties of an element
DELETE Delete Delete an item or collection of items (eg, move a teaser to recycle bin)
Important! POST and PUT are not interchangeable. Each of the commands fulfills its specific function.

In general, the query looks like this:
http://api.mgid.com/v1/module/controller/action?token=_client's_token_&parameter_1=value_of_parameter_1&parameter_2=value_of_parameter_2&parameter_3=value_of_parameter_3

Identification

For identification the Mgid REST API uses a unique token consisting of 32  characters which is passed in client's request. To obtain a valid token client  
should use a special API function.

Every request sent to the Mgid REST API must contain the API token

Mgid REST API answer

In response to a request to the REST API server always returns the HTTP response with a status code , depending on the result of the query.

Answer code Description
200 OK The query has been successfully
processed
400 Bad Request Syntax error
404 Not Found Item or page not found

Format of the returned data

The returned data can be formatted as JSON, or XML.  The default format is JSON. The request header is used to specify the format in which the data is  
returned. The client sends an Accept header, which indicates desired response format:  
Accept: application / xml  
or  
Accept: application / json

Description of the response format is sent in the response header Content Type. The data returned is the answer is a JSON string (http://json.org/json ru.html), which generally looks as follows:  

{
   "element_1"   "value_of_element_1"    
"element_2" "value_of_element_2"  
"element_3":    {
      "property_1_of_element_3"      "value_of_property_1_of_element_3"       
"property_2_of_element_3":       [
         "value_1_of_property_2_of_element_3"          
"value_2_of_property_2_of_element_3"
      ]       
   }    

  . . . .  
}

If an error has occurred during the execution of the query   the description corresponding to the error is returned, such as:

{ "errors": [ "[_error_description_]" ] }

Working with clients

Getting the current client's token

Method URL
POST api.mgid.com/v1/auth/token

Transferred parameters:

Parameter Value
email E-mail of the client, specified at registration in Mgid system
password Password of the client, received during registration in Mgid system

Returns an answer:

{
"token":"_current_token_",
"refreshToken":"_token_for_refresh_"
"idAuth":"_ID_of_client_account_"
}

_current_token_  is used to identify the client;  
_token_for_refresh_ will be used in future versions to update an overdue current token.

Working with widgets

Getting statistics of composite widgets

Method GET
URL api.mgid.com/v1/publishers/{authId}/widgets

Transfered parameters (required parameters are marked in red):

Parameter Value
token _clients_token_
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days
siteId If specified - displays statistics only for the widgets associated with the site(s). Can accept multiple values separated by commas.
widgetId Сomposite widget ID. If specified - displays statistics only for the specified widget(s). Can accept multiple values separated by commas.

Answer returned:

{  
  "_dateInterval_":{  
     "_widgetId_":{  
        "impressions":"_impressions_",
        "realImpressions":"_real_impressions_",
        "visibilityRate":"_visibility_rate_%_",
        "clicks":"_clicks_",
        "ctr":"_ctr_"
        "revenue":"_revenue_$_",
        "cpc":"_cpc_¢_",
        "cpm":"_cpm_$_"
     }
  }
}

Getting statistics of composite widgets by sub-ids

Method GET
URL api.mgid.com/v1/publishers/{authId}/widget-sub-ids-stat

Transfered parameters (required parameters are marked in red):

Parameter Value
token _clients_token_
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days
widgetId Сomposite widget ID

Answer returned:

{
   " _subid_": {
       "subid":  _subid_,
       "shows": "_shows_",
       "real_shows": "_real_shows_",
       "visibility_rate": "_visibility_rate_",
       "clicks": "_clicks_",
       "wages": "_wages_",
       "cpm": "_cpm_",
       "cpc": "_cpc_",
       "ctr": "_ctr_"
   }
   " _subid_": {
       "subid":  _subid_,
       "shows": "_shows_",
       "real_shows": "_real_shows_",
       "visibility_rate": "_visibility_rate_",
       "clicks": "_clicks_",
       "wages": "_wages_",
       "cpm": "_cpm_",
       "cpc": "_cpc_",
       "ctr": "_ctr_"
   }

}

Getting sub-id statistics of composite widgets by date

Method GET
URL api.mgid.com/v1/publishers/{authId}/widget-sub-id-stat-by-date

Transfered parameters (required parameters are marked in red):

Parameter Value
token _clients_token_
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days
widgetId   Сomposite widget ID
widgetSubId Сomposite widget subID ID

Answer returned:

 " _date_": {
       "date":  _date_,
       "shows": "_shows_",
       "real_shows": "_real_shows_",
       "visibility_rate": "_visibility_rate_",
       "clicks": "_clicks_",
       "wages": "_wages_",
       "cpm": "_cpm_",
       "cpc": "_cpc_",
       "ctr": "_ctr_"
   }

Getting statistics by countries

Method GET
URL api.mgid.com/v1/publishers/{authId}/widget-stat-by-countries

Transfered parameters (required parameters are marked in red):

Parameter Value
token _clients_token_
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days
widgetId   Сomposite widget ID

Answer returned:

{
    "RU": {                          //country code in ISO 3166-1
	"shows": "_shows_",
	"real_shows": "_real_shows_",
	"visibility_rate": "_visibility_rate_",
	"clicks": "_clicks_",
	"wages": "_wages_",
	"cpm": "_cpm_",
	"cpc": "_cpc_",
	"ctr": "_ctr_"
	}
}

Full list of country codes here

Getting daily statistics by countries

Method GET
URL api.mgid.com/v1/publishers/{authId}/widget-stat-by-country

Transfered parameters (required parameters are marked in red):

Parameter Value
token _clients_token_
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days
widgetId   Сomposite widget ID
countryIso Country ISO code. Full list of country codes here

Answer returned:

{
    "RU": {                          //country code in ISO 3166-1
	"shows": "_shows_",
	"real_shows": "_real_shows_",
	"visibility_rate": "_visibility_rate_",
	"clicks": "_clicks_",
	"wages": "_wages_",
	"cpm": "_cpm_",
	"cpc": "_cpc_",
	"ctr": "_ctr_"
	}
}

Working with sites

Getting statistics of sites

Method GET
URL api.mgid.com/v1/publishers/{authId}/sites-stat

Works for exchange and internal exchange only.

Transfered parameters (required parameters are marked in red):

Parameter Value
token _clients_token_
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days
siteId Site ID. If specified - displays statistics only for the specified site(s). Can accept multiple values separated by commas.

Answer returned:

{
   "_siteId_": {
       "_dateInterval_": {
           "pclicksIntExchange": _clicks_,
           "pageViews": _page_views_,
           "showsIntExchange": _shows_,
           "ctrIntExchange": "_ctr_"
       }
   }
}

Custom reports

Method GET
URL api.mgid.com/v1/publishers/{authId}/widget-custom-report

Transfered parameters (required parameters are marked in red):

Parameter Value
token client's token
dateInterval Interval of time you need to get a statistics. Valid values:

  • interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd
  • all
  • thisWeek
  • lastWeek
  • thisMonth
  • lastMonth
  • lastSeven
  • today
  • yesterday
  • last30Days

In addition, you can transfer the hour intervals:

  • startHour - start hour 0-23
  • endHour - end hour 0-23
siteId Client's site ID
dimensions list of fields to group. It can take multiple values separated by a comma. Valid values are:

  • date
  • widgetId
  • deviceType
  • subId
  • countryIso
metrics list of fields for extracting indicators. It can take multiple values separated by a comma. Valid values are:

  • shows
  • realShows
  • visibilityRate
  • clicks
  • wages
  • cpm
  • vCpm
  • cpc
  • ctr
widgetId conposite widget ID 
deviceType device type (desktop, tablet, mobile)
countryIso country code (alpha2)
sortBy sort by field (can take one of the transmitted values dimensions or metrics), if not passed, sorts by the first parameter from dimensions
sortMethod direction of sorting (asc, desc), if not sent then applied ASC direction
timeZone Timeshift of statistics. Available list of timeZones here ( TZ )

 

Related posts

ADS.txt manual

Due to the recent standards implemented by IAB and the Coalition for Better Ads, in order to support Internet transparency in the programmatic advertising ecosystem, these governing bodies are now requiring our publishers to create a public record of Authorized Digital Sellers or simply “ADS.txt.” It gives publishers control over their inventory in the market,

Read More