REST API Marketgid for advertisers (english version)

Содержание

The main provisions of REST API

REST API allows you to integrate external applications with Marketgid online
advertising system.
API provides the ability to retrieve, add, and modify the data. Practically each  object in Marketgid (whether it's a client, an advertising company, a teaser, etc.) can  be controlled by API. Marketgid 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. Marketgid API is a "RESTful  Web API". The API uses the following REST commands:
● GET
● PUT
● PATCH
● POST
● DELETE

These commands correspond to certain actions within the Marketgid system.

The query parameters are case sensitive.

Get an item or a collection of items (for example, a list of advertising campaigns):    

Command Action Description

POST

Create

Description

GET

Get (read)  

Creates a new element (eg, a teaser)

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.


Marketgid API URL
Marketgid REST API for clients is available at:

http://api.marketgid.com/v1

In general, the query looks like this:
http://api.marketgid.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 Marketgid 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 Marketgid REST API must contain the API token

Marketgid REST API answer


In response to a request 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

* Currently, the issuance of the error code is being finalized

The 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:

or

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:

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


 Working with clients


Getting the current client's token

Method POST

URL

api.marketgid.com/v1/auth/token

transferred parameters:

 Parameter Value

email

E mail of the client, specified at registration in Marketgid system

 password

Password of the client, received during registration in Marketgid system

Returns an answer:


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

Getting information about the current financial status of the client

Method GET

URL

api.marketgid.com/v1/clients/_identifier_of_client's_account_?token=_client_token_

Returned answer:


All refunds are made in cents (0.01$).balance can have both positive and negative value. Available funds are defined as: balance + credit. Funds spent on advertising: income  balance.

Working with client's advertising campaigns

 Getting a collection of client's advertising campaigns

Method GET

URL

api.marketgid.com/v1/goodhits/clients/_client's_accont_ID_ / campaigns [/_ad_campaign_ID_]

 If _ad_campaign_ID_ was not passed, then the method returns a collection of client's advertising campaigns. If the ID has been passed correctly, it returns information only about specific ad campaign.

transferred parameters (required parameters marked in red):

Parameter Value

token

_client's_token_

Fields

array of client's properties, information on which you
need to get.(
 example: fields=['name','ipsFilter','domainsFilter']).
If the parameter is not passed, then all properties are returned.

The list may include following properties:
id - ad campaign id
name - ad campaign id
status - ad campaign status
ipsFilter - IP filter settings
domainsFilter - domain filter settings
widgetsFilterUid - widget filter settings

limit

turns on the pagination, limiting the number of campaigns displayed on the page.

start

uses for navigation for pagination pages. The default is 0.

Answer returned:

Possible errors:

  • [ERROR_TOO_MANY_CAMPAIGNS_USE_PARAMS_LIMIT_AND_START] - if the user has more than 500 campaigns and the optional limit parameter is not specified
  • [ERROR_MAX_LIMIT_PER_PAGE_500] - if the additional parameter limit is specified and it is more than 500

Status property indicates current campaign state and status.

Description of status value returned:

id Description

1

Campaign is blocked due to end date

2

Campaign has reached total budget limit

3

Campaign has reached total clicks limit

4

Campaign is blocked by manager of client

5

Campaign is blocked due to negative balance

6

Campaign is unlimited and active

7

Campaign hasn't reached its daily limit

8

Yesterday campaign has reached its daily clicks or budget limit and is active

9

Campaign has reached its daily budget limit

10

Campaign has reached its daily clicks limit

11

Campaign is paused due to time schedule settings

12

Campaign stopped because the client delayed
13 Campaign stopped by manager
14 Campaign deleted
15 Campaign stopped because the client rejected
17 Campaign stopped due to conversion limit
19 Campaign stopped due to violation of the creativity rules

IpsFilter property displays the IP filter settings of an advertising campaign (teasers of this campaign should not be shown to visitors with this IP). 

_IP_filter_type_ can take the following values:

  • off - the filter is disabled
  • except - "except" filter  
  • ips - a list of IP address ranges for filtering as an array. 

_spent_by_the_client_for_today_ in $

Getting advertising campaign statistics by site

Method GET

URL

api.marketgid.com/v1/goodhits/campaigns/_ad_campaign_ID_/quality-analysis/uid?token=_client's_token_

transferred parameters (required parameters marked in red):

Parameters Values

token

_client's_token_

campaignId

_ad_campaign_ID_

dateInterval

Period for which you need to get statistics. If interval is not specified, returns statistics for 90 days. Valid values are:

  • interval - need to specify startDate/endDate in format yyyy-mm-dd
  • all - all time
  • thisWeek - current week
  • lastWeek - last week
  • thisMonth - current month
  • lastMonth - last month
  • lastSeven - last 7 days
  • today - today
  • yesterday - yesterday
  • last30Days - last 30 days

uid

site uid. If specified, displays information only for this site.

Answer returned:

 Advertising campaigns detailed daily statistics

Method GET

URL

api.marketgid.com/v1/goodhits/campaigns/_adcampaign_id_/statistics?token=_client's_token_


transferred parameters (required parameters are marked in red):

Parameters Value

type

Statistics type. Values:  byClicksDetailed

date

Format date: YYYY-MM-DD


Returned values:
If the request is correctly, it returns an array of data in the next format:

Advertising campaigns daily statistics

Метод GET
URL api.marketgid.com/v1/goodhits/clients/{clientId}/campaigns-stat?token={accessToken}

Transferred parameters:

Parameter Value
token client's token
dateInterval

Period for which you need to get statistics. If interval is not specified, returns statistics for 90 days. Valid values are:

  • interval - need to specify startDate/endDate in format yyyy-mm-dd
  • all - all time
  • thisWeek - current week
  • lastWeek - last week
  • thisMonth - current month
  • lastMonth - last month
  • lastSeven - last 7 days
  • today - today
  • yesterday - yesterday
  • last30Days - last 30 days

Answer:

If the customer has conversion settings - additional data transferred:

  • buy - quantity of buying conversions
  • buyCost - cost of buying
  • decision - quantity of decision conversions
  • decisionCost - cost of decision
  • interest - quantity of interest conversions
  • interestCost - cost of interest
  • convertionCost - conversions profit
  • revenue - revenue
  • epc - earn per click
  • profit - revenue - spent

If there are some errors:

[THERE_NO_DATA_IN_CHOSEN_PERIOD] - if there is no data in chosen period

[INVALID_VALUE_FOR_INTERVAL] - invalid value for interval

Creating a new ad campaign (with all settings)

Method POST

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns?token=_client's_token_

Request example:

Transferred parameters (red - required; blue - required, if parent parameter transferred):

Section 1

Parameters Value
name Campaign name. Must be unique. 128 symbols max.
enabledGeoTargetingFlag Flag on/off GeoTargeting
geoTargets List of countries and cities (regions) for targeting. Example:

{'method':'set','cities':['2'],'countries':['ru']}

language language of ad campaign
startDate Campaign start date YYYY-MM-DD
campaignType product/content. If campaign_type didn't transfer campaign_type = product

Possible errors for this section:

 

Section 2
If at least one of the utm_source, utm_campaign, utm_medium transferred, then all three are required

Parameters Value
utm_source 0, 9, A Z, a z, _ + & = (up to 200 symbols)
utm_campaign 0, 9, A Z, a z, _ + & = (up to 200 symbols)
utm_medium 0, 9, A Z, a z, _ + & = (up to 200 symbols)
utm_custom Macroses: {widget_id}/{teaser_id}/{campaign_id}/{category_id} etc

Possible errors for this section:

 

Section 3
If limitType parameter transferred, then limit type must be specified (day or total)

Parameters Value
limitType

clicks_limits - limit on clicks, budget_limits - limit on budget

dailyLimit

Setting the limit per day.

For clicks_limits  must be an integer value. Min  50. If a value is empty - campaign have no limits.

For budget_limits  The value of 2 characters after the decimal point (up to hundredths).

overallLimit

Setting the limit on the campaign in general.

For clicks_limits – must be an integer value and more than a dailyLimit, if specified. If value is empty - campaign has no limits.

For budget_limits value with 2 characters after the decimal point (up to hundredths). Must be more than a dailyLimit, if specified. If value is empty - campaign have no limits.

splitDailyLimitEvenly Option of evenly daily traffic distribution. 0 - on, 1 - off

Possible errors for this section:

 

Section 4

Parameters Value
browserTargets _browser1_, _browser2_, _browser3_
osTargets _os1_,_os2_,_os3_

Possible errors for this section:

Answer returned:

Creating a new ad campaign

Method POST
URL api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns?token=_client's_token_

Transferred parameters (required parameters are marked in red):

Parameters Values
name Campaign name
enabledGeoTargetingFlag Flag on/off GeoTargeting
geoTargets
List of countries and cities (regions) for
(parameter is required if targeting:
enabledGeoTargetingFlag =1)
{'method':'set','cities':['2'],'countries':['ru']}
language language of ad campaign
startDate campaign start date YYYY-MM-DD
campaignType product | content. If parameter didn't send campaign_type = product

Answer returned:

If there already exists an ad campaign with the name specified in the request, then new campaign will not be created and system return error:

UTM markup settings for ad campaign

Method PUT

URL

api.marketgid.com/v1/goodhits/campaigns/_campaign_ID_/utmtracking/?token=_client's_token

 transferred parameters:

Parameters Value

utm_source

Standard setting Google Analytics to track traffic source

utm_campaign

Standard setting Google Analytics to track purchases traffic campaign

utm_medium

Standard setting Google Analytics to track traffic channel

utm_custom

Custom markup. Ability to specify custom settings, which
will be added to the links campaign teaser

Values for Google Analytics (utm_source, utm_campaign, utm_medium) must be given a single query. If you are using one of the this parameters, other are required. Error if one of values is empty: [UTM_TAGGING_FIELDS_MUST_NOT_BE_EMPTY]  

When you specify the default settings Google Analytics also automatically added utm_content  and utm_term . In tag utm_content  automatically substituded ID ads.  utm_term=_site_ID_

Utm_custom ,should not exceed 200 characters, or system return error:
[UTM_CUSTOM_TOO_LONG_STR]  

Valid characters are: 0 9, A Z, a z,   _ + & = . And macros: {widget_id},  {teaser_id}, {campaign_id}, {category_id}.  

Or system return error:  [WRONG_UTM_CUSTOM_FORMAT]
If you pass an empty field markup is disabled. If the settings are saved successfully, system return campaign ID:

 

Setting limits on the advertising campaign

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns/_campaign_ID_


transferred parameters (required parameters are marked in red):

Parameters Value

token

 _client's_token_

limitType

clicks_limits - limit on clicks

budget_limits - limit on budget

dailyLimit

Setting the limit per day.

For clicks_limits  must be an integer value. Min  50. If a value is empty - campaign have no limits.

For budget_limits  The value of 2 characters after the decimal point (up to hundredths).

overallLimit

Setting the limit on the campaign in general.

For clicks_limits – must be an integer value and more than a dailyLimit, if specified. If value is empty - campaign have no limits.

For budget_limits value with 2 characters after the decimal point (up to hundredths). Must be more than a dailyLimit, if specified. If value is empty - campaign have no limits.

splitDailyLimitEvenly

Option of evenly daily traffic distribution. 0 - on, 1 - off

  • The daily limit can not be less than $10
  • The total limit can not be less than the daily limit
  • Step limit - 1 cent

A system returns  _campaign_ID_ if  all done:

Block / unblock the advertising campaign

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns/_campaign_ ID_


transferred parameters:

Parameters Value

token

 _token_

whetherToBlockByClient

0 – unlock ad campaign
1 — lock ad campaign

BlockByClientReason

(if whetherToBlockByClient=1, then required parameter  )  

 _blocking reason_

 

Getting the creation date of advertising campaigns

Method GET

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns/_adcampaign_id_?token=_client's_token_&fields=['whenAdd']

Transferred parameters:

Parameters Values

fields

whenAdd

Answer returned:

Setting the coefficient of selective auction of an advertising campaign

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_clientID_/campaigns/_campaignID_?token=_client's_token_&qualityFactor={"_widgetUid1_s_sourceId1_":_qf1_,"_widgetUid2_s_sourceId2_":_qf2_,…}

Transferred parameters (required parameters marked in red):

Parameters Values

token

_client's_token_

clientId

_client_ID_

campaignId

_ad_campaign_ID_

qualityFactor

Contains a widgetUID and a new quality factor on the site. There can be several pairs in json format: {"_widgetUid1_":_qf1_,"_widgetUid2_":_qf2_,"_widgetUid3_":_qf3_}

sourceId

Contains sourceId. Can be set through "s". Example: {"_widgetUid1_s_sourceId1_":_qf1_}

Answer returned:

If new coefficient not included in the allowable range, it returns:

If site is not in the list, an error returns:

 

Advertising campaigns targeting settings

Setting up the geo targeting of advertising campaigns

Getting geotargeting settings ad campaign of client:

Method GET

URL

api.marketgid.com/v1/goodhits/campaigns/_campaign_ID_/targetings/geo?token=_client's_token_

Answer returned:

Section "actual"  contains the current geotargeting.  Section "request"  updated geotargeting settings that will be applied (or in the near future, or from the following day). If geotargeting settings are not used, it returns an answer like:

 

 Getting a list of available countries for setting up geo targeting

Method GET

URL

api.marketgid.com/v1/dictionaries/geo?token=_client's_token_


transferred parameters:

Parameter Value

type

countries

Returns an array of countries that can be used for setting geotargeting:

 Getting a list of available regions (cities) for geo targeting settings

Method GET

URL

api.marketgid.com/v1/dictionaries/geo?token=_client's_token_


transferred parameters:

Parameters Value Comments

type

cities

countries

 ['_ two_letter_country_code _',....]

 An array of country codes for which you need to get a cities (regions) list.

Returns an array of regions (cities) that can be used for geo targeting:

 

Editing geo targeting settings for an advertising campaign

Method PUT

URL

api.marketgid.com/v1/goodhits/campaigns/_campain_ID_/targetings/geo?token=_client's_token_


transferred parameters:

Parameter Value

targets

 The list of countries and cities (regions) for targeting:
 { 'method':'set', 'cities': [ _city_ID_, . . . . ], 'countries':
[ two_letter_country_code _,  . . . . . ] }

If filled cities and countries in the priority will be countries parameter.

enabledFlag

 Flag on/off geo targeting(1/0)

If the request is correct, will be returned  ID edited ad campaign:

If you do not specify any parameters or configured incorrectly, the changes
settings will not be saved and will return an error message:

 

 Editing browser targeting settings for advertising campaign

Method PUT

URL

api.marketgid.com/v1/goodhits/campaigns/_ad_campaign_ID_/targetings/browsers?token=_client's_token_


transferred parameters:

Parameter Value

targets

_ editing_method_ , _ browser_,_ browser_.....

enabledFlag

0 – target off1 — target on

 Possible values for the  _editing_method_ :
 include - inclusion of a browser in the list for targeting

Possible values for _browser_ :

Name Value

Google Chrome

chrome

Safari

safari

Opera Mini

operamini

Opera Mobile

operamoblie

Opera

opera

Firefox

firefox

Internet Explorer

msie

Others

others

Upon successful saving settings system returns campaign ID:
 

 

Editing IP addresses filter settings for advertising campaign

Method PATCH

 URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns/_ad_campain_ID_?token=_client's_token_


transferred parameters:

Parameter Value

ipsFilter

 _ editing_methods _ , _filter_type_, IP1,IP2....


Settings:

  •  Editing methods:
  • include include an address in the list
  • exclude remove an address from the list
  • Filter type :
  • except
  • only
  • off – filter off

IP can be specified as single or as subnets (192.168.0.1/24)

Upon successful saving settings system returns campaign ID:

 

Editing operating system settings for advertising campaign

 

Method PUT

URL

api.marketgid.com/v1/goodhits/campaigns/_ad_campaign_ID_/targetings/operatingsystems?token=_client's_token_

transferred parameters:

Parameter Value

enabledFlag

on/off OS targeting, on=1, off=0

targets

_editing_method_,_OS1_,_OS2_,_OS3_

Operating systems: 

name version code
Android 9.xx android90mobile
Android 8.xx android80mobile
Android 7.xx android70mobile
Android 6.xx android60mobile
Android 5.xx android50mobile
Android 4.4 android44mobile
Android 4.3 android43mobile
Android 4.2 android42mobile
Android 4.1 android41mobile
Android 4.0 android40mobile
Android 3.хх android3mobile
Android 2.3 android23mobile
Android 2.2 and lower android22mobile
iOS 9.хх ios9mobile
iOS 8.хх ios8mobile
iOS 7.хх ios7mobile
iOS 6.хх ios6mobile
iOS 5.хх ios5mobile
iOS 4.хх and lower ios4mobile
iOS 11.xx ios11mobile
iOS 10.хх ios10mobile
Other Mobile OS othermobile
Android 9.xx android90tablet
Android 8.xx android80tablet
Android 7.xx android70tablet
Android 6.xx android60tablet
Android 5.xx android50tablet
Android 4.4 android44tablet
Android 4.3 android43tablet
Android 4.2 android42tablet
Android 4.1 android41tablet
Android 4.0 android40tablet
Android 3.хх android3tablet
Android 2.3 android23tablet
Android 2.2 and lower android22tablet
iOS 9.хх ios9tablet
iOS 8.хх ios8tablet
iOS 7.хх ios7tablet
iOS 6.хх ios6tablet
iOS 5.хх ios5tablet
iOS 4.хх and lower ios4tablet
iOS 11.xx ios11tablet
iOS 10.хх ios70tablet
Other Tablet OS othertablet
Mac OS macos
Other Desktop OS otherdesctop
Windows OS windowsos

Editing methods :

 include - add OS to the list
 exclude - remove OS from the list
Upon successful saving settings system returns campaign ID:

Editing filter settings on the sites for advertising campaign by UID

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/campaigns/_ad_campaign_ID_?token=_client's_token_

transferred parameters:

Parameter Value

widgetsFilterUid

editing_method, filter_type, uid1,uid2…

you can send sub-source parameters in brackets filter_type, uid1(subid subid sibid),uid2… or through "s" filter_type, UID1sSUBID1...

block-widget-priority

For the edit method include, when it receives a request to add sub_id, it checks whether the source is added to the filter, if added, then the record of the source is ignored. Thus, using this parameter, you can slightly change the query processing logic.

Editing methods:

  • include - include in list
  • exclude - exclude from the list

Filter types:

  • only
  • except
  • off


On success - returns the identifier of editable ad campaign

Example response with errors in the data - sites not transferred:

{"errors":["[WIDGETS_IDS_CANNOT_BE_EMPTY]"]}
Example response with errors in the data - non-existing sites id transferred:
{"errors":["[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]"],"data":["1000000001000"]}
Example response with errors in the data - filter parameters not transferred(include|exclude,off|only|except) or transferred in wrong way:
{"errors":["[ERROR_NOT_VALID_FILTER_TYPE]"]}
If transferred valid & non-valid IDs ("widgetsFilter": "include, only, 1000000, 111111, 109") - valid IDs will be written in database, for non-valid will be the answer:
{"id":_ad_campaign_ID_, "errors":"[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]","data":["1000000","111111"]}
When sites not passed - it's a non-valid situation.

Working with client's teasers

Constants and identifiers in use

Teasers categories and category ID:

Currency code to display the price of the product:

Currency ID in MG system Relevant international three-character code

5

USD

6

EUR

7

GBP

10

CAD

12

INR

22

AUD

24

ZAR

43

AED

 Teaser status:

Status Description

onModeration

Teaser on moderation

rejected

Teaser is rejected

active

Teaser is active

new

New teaser, don't have CTR yet

goodPerformance

Teaser is in shows

badPerformance

Teaser have no shows in one or more regions because have low rating. It is necessary to set a higher price per click or replace the teaser on the other, which could provide a higher CTR

blocked

Blocked teaser

campaignBlocked

Blocked campaign

 Getting a list of client teasers

Method GET

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/teasers[/_teaser_ID_]


If
 _teaser_ID_ is not passed, then method returns a list of client teasers. If _teaser_ID_ is passed, then method returns information about current teaser.

transferred parameters (required parameters are marked in red):

Parameters Value

token

_client's_token_

fields
(optional, use if passed
 _teaser_ID_)

Array of teaser properties, information
about which  necessary to obtain(for example:
fields=['title','url','statistics']).  If the parameter is not passed, then returns  all  Properties.

campaign

Getting a list of client's teasers by campaign ID

limit

limiting the number of teasers displayed on the page. If doesn't set - shows all teasers. Possible error when using the option limit: ["[ERROR_MAX_LIMIT_PER_PAGE_{max_allowed_limit}]"]

start

allows to navigate through pagination pages. Default - 0


Answer returned:
 

If teaser ID is incorrect then system returns error:

 

 Creating a new teaser for ad campaign

Method POST

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/teasers?token=_clients_token_


transferred parameters (required parameters are marked in red)

Parameters Value

url

URL advertising links. It's recommended to use %26 instead of during parameters transmission

campaignId

Campaign ID to which is teaser added

title

Teaser title(up to 65 characters)

advertText

Advertising text(up to 75 characters)

imageLink

Link to teaser image. Minimum size 492x328 pixels

priceOfClick

Price per click, cents, with tenths. As a separator
between the whole number and the fraction can use acomma or period.

cropWidth

The size of rectangle in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. cropWidth cannot be less than 492px. If cropLeft is filled, then cropWidth cannot be less than cropWidth + cropLeft and cannot be larger than the image width imageLink

cropTop

The offset of rectangle from the top edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty, but can not be less than the height of the image imageLink minus 328px

cropLeft

The offset of rectangle from the left edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty. cropWidth + cropLeft cannot be larger than the image width ImageLink

cropWidthQuadratic

The size of square in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. cropWidthQuadratic cannot be less than 328px. If cropLeftQuadratic is filled, then cropWidthQuadratic cannot be less than cropWidthQuadratic + cropLeftQuadratic and cannot be greater than the width of the image imageLink

cropTopQuadratic

The offset of square from the top edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty, but can not be less than the height of the image imageLink minus 328px

cropLeftQuadratic

The offset of square from the left edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty. cropWidthQuadratic + cropLeftQuadratic can not be larger than the image width imageLink

whetherShowGoodPrice

Flag display the price of goods (1/0)

If whetherShowGoodPrice = 1 parameters currency, goodPrice, goodOldPrice are required. If whetherShowGoodPrice = 0 then the following parameters will be ignored.

     currency

Currency ID to display the price of the product

     goodPrice

Price of the goods in a specified currency

     goodOldPrice

Old price of the goods.

 Answer returned:
Upon successful creation of the teaser response is returned:

Returns an error name  if try to creating teaser was failure:

The list of possible errors returned in the creation an editing teaser of campaign:

_ERROR_NAME_ specification

ERROR_PARAMETER_WHETHERSHO WGOODPRICE_CAN_NOT_BE_EMPTY

Not passed a required parameter whetherShowGoodPrice

ERROR_PARAMETER_PRICEOFCLICK_ CAN_NOT_BE_EMPTY

Not passed a required parameter priceOfClick

ERROR_PARAMETER_CATEGORY_CAN_NOT_BE_EMPTY

Not passed a required parameter category

ERROR_ADVERT_TEXT_TOO_LONG

Advertising text (parameter advertText) exceeds the maximum allowed length (no more than 75 characters)

ERROR_PARAMETER_TITLE_CAN_NOT_BE_EMPTY

Not transferred teaser title (required parameter title)

ERROR_TITLE_TOO_LONG

Title teaser (parameter title) exceeds the maximum allowed length (no more than 65 characters)

ERROR_PARAMETER_IMAGELINK_CAN_NOT_BE_EMPTY

Not assigned image link for the teaser (required parameter imageLink)

ERROR_PARAMETER_CAMPAIGNID_CA N NOT_BE_EMPTY

Not transmitted campaign ID that creates teaser (required parameter campaignId)

ERROR_PARAMETER_URL_CAN_NOT_B E _EMPTY

Not assigned to an advertising link to the teaser (required parameter url)

[ERROR_PARAMETER_CATEGORY_INCORRECT_FOR_THIS_CAMPAIGN_TYPE]

Improperly selected category for this type of campaign

Editing the ad campaign teaser settings

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID _?token=_client's_token_


 transferred parameters:

Parameters Value

url

URL advertising links

campaignId

Campaign ID to which is teaser added

title

Teaser title(up to 65 characters)

advertText

Advertising text(up to 75 characters)

imageLink

Link to teaser image. Minimum size 492x328 pixels

category

Category ID of teaser

priceOfClick

Price per click, cents, with tenths. As a separator
between the whole number and the fraction can use acomma or period.

cropWidth

The size of rectangle in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty.

cropTop

The offset of rectangle from the top edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty.

cropLeft

The offset of rectangle from the left edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty.

cropWidthQuadratic

The size of square in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty.

cropTopQuadratic

The offset of square from the top edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty.

cropLeftQuadratic

The offset of square from the left edge in pixels, that will be cut from uploaded image (imageLink) for the teaser's image creation. Can be empty.

whetherShowGoodPrice

Flag display the price of goods (1/0)

If whetherShowGoodPrice = 1 parameters currency, goodPrice, goodOldPrice are required. If whetherShowGoodPrice = 0 then the following parameters will be ignored.

     currency

Currency ID to display the price of the product

     goodPrice

Price of the goods in a specified currency

     goodOldPrice

Old price of the goods.

If any of the required parameters wasn't passed, system returns error.

For example, not transmitted campaignId :

If teaser on moderation, returns error.

 Changing advertising campaign teaser's CPC

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_?token=_clients_token_

transferred parameters:

Parameter Value

priceOfClickByLocation

Installed CPC in tenth of cents for all geo groups. Can be used a period or comma as a delimiter. 

priceOfClickByLocation_{geo_zones_groups_id}

Installed CPC in tenth of cents for for a specific geo group. Can be used a period or comma as a delimiter.

 Answer returned.
If all done correctly, system return an answer:

Some errors:
● if the parameter CPCs not specified or incorrect:

● if the price is not indicated or specified is not a valid value:

● if the price is less than minimum:

● if the price is higher than  maximum:

● if teaser on moderation:

 

Block / unblock a teaser for the advertising campaign

Method PATCH

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_?token=_client's_token_


transferred parameters:

Parameters Value

whetherToBlockByClient

1 — block
0 — unblock

Answer returned.
If the operation is successful, it returns teaser ID:

{"id":"_teaser_ID_"}

Removing a teaser (move to bin)

Method DELETE

URL

api.marketgid.com/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_?token=_client's_token_


transferred parameters:

Parameters Value

reason

A reason of Deleting. Max 225 symbol


Answer returned.
If the operation is successful, it returns teaser ID which was moved to bin:

If a teaser with the specified ID does not exist in the system or have already been
moved to the bin, then the message will be returned:

Похожие статьи

Типы лендингов

Чтобы достигнуть оптимального баланса между интересами рекламодателей, запросами вебмастеров и пользовательским опытом, мы представляем...

Read More