get

Returns reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, ad exchanges (SSPs), Crypta segments for user profile targeting, and other information.

  1. Request
  2. Response
  3. Examples

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { /* params */
    "DictionaryNames": [( "Currencies"
                        | "MetroStations"
                        | "GeoRegions"
                        | "TimeZones"
                        | "Constants"
                        | "AdCategories"
                        | "OperationSystemVersions"
                        | "ProductivityAssertions"
                        | "SupplySidePlatforms"
                        | "Interests"
                        | "AudienceCriteriaTypes"
                        | "AudienceDemographicProfiles"
                        | "AudienceInterests" ), ... ] /* required */
  }
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / GetRequest (for SOAP)
DictionaryNamesarray of DictionaryNameEnumNames of the reference lists to get.Yes

Response

Response structure in JSON format:

{
  "result": {
    "Currencies": [{  /* CurrenciesItem */
      "Currency": (string), /* required */
      "Properties": [{  /* ConstantsItem */
        "Name": (string), /* required */
        "Value": (string) /* required */
      }, ... ] /* required */
    }, ... ],
    "MetroStations": [{  /* MetroStationsItem */
      "GeoRegionId": (long), /* required */
      "MetroStationId": (long), /* required */
      "MetroStationName": (string) /* required */
    }, ... ],
    "GeoRegions": [{  /* GeoRegionsItem */
      "GeoRegionId": (long), /* required */
      "GeoRegionName": (string), /* required */
      "GeoRegionType": (string), /* required */
      "ParentId": (long) /* nillable */  
    }, ... ],
    "TimeZones": [{  /* TimeZonesItem */
      "TimeZone": (string), /* required */
      "TimeZoneName": (string), /* required */
      "UtcOffset": (int) /* required */
    }, ... ],
    "Constants": [{  /* ConstantsItem */
      "Name": (string), /* required */
      "Value": (string) /* required */
    }, ... ],
    "AdCategories": [{  /* AdCategoriesItem */
      "AdCategory": (string), /* required */
      "Description": (string), /* required */
      "Message": (string) /* required */
    }, ... ],
    "OperationSystemVersions": [{  /* OperationSystemVersionsItem */
      "OsName": (string), /* required */
      "OsVersion": (string) /* required */
    }, ... ],
    "SupplySidePlatforms": [{  /* SupplySidePlatformsItem */
      "Title": (string) /* required */
    }, ... ],
    "Interests": [{  /* InterestsItem */
      "InterestId": (long),
      "ParentId": (long),
      "Name": (string),
      "IsTargetable": ( "YES" | "NO" )
    }, ... ],
    "AudienceCriteriaTypes": [{ /* AudienceCriteriaTypesItem */
      "Type": (string), /* required */
      "BlockElement": (string),  /* required */
      "Name": (string),  /* required */
      "Description": (string),  /* required */
      "CanSelect": ( "ALL" | "EXCEPT_ALL" ) /* required */
    }, ... ],
    "AudienceDemographicProfiles": [{ /* AudienceDemographicProfilesItem */
      "Id": (long), /* required */
      "Type": (string), /* required */
      "Name": (string), /* required */
      "Description": (string) /* required */
    }, ... ],
    "AudienceInterests": [{ /* AudienceInterestsItem */
      "InterestKey": (long), /* required */
      "Id": (long), /* required */
      "ParentId": (long), /* required */
      "Name": (string), /* required */
      "Description": (string), /* required */
      "InterestType": ( "SHORT_TERM" | "LONG_TERM" | "ANY" )  /* required */
    }, ... ]
  }
}
ParameterTypeDescription
Result structure (for JSON) / GetResponse (for SOAP)
AdCategoriesarray of AdCategoriesItem

Special categories of advertised products and services.

See the section Special category.

Constantsarray of ConstantsItemRestrictions on parameter values.
Currenciesarray of CurrenciesItemCurrency exchange rates, currency parameters, and restrictions.
GeoRegionsarray of GeoRegionsItemRegions.
MetroStationsarray of MetroStationsItemMetro stations (only for Moscow, Saint Petersburg, and Kiev).
OperationSystemVersionsarray of OperationSystemVersionsItemVersions of operating systems for advertising mobile apps.
ProductivityAssertionsarray of ProductivityAssertionsItemThis parameter is obsolete and is not returned.
TimeZonesarray of TimeZonesItemTime zones.
SupplySidePlatformsarray of SupplySidePlatformsItemAd exchanges (SSPs).
Interestsarray of InterestsItemInterests in mobile app categories.
AudienceCriteriaTypesarray of AudienceCriteriaTypesItemDemographic and behavioral characteristics.
AudienceDemographicProfilesarray of AudienceDemographicProfilesItemSegments based on demographic and behavioral characteristics for targeting by user profile.
AudienceInterestsarray of AudienceInterestsItemSegments based on user interests for targeting by user profile.
AdCategoriesItem structure
AdCategorystringDesignates a special category (the AdCategories ad parameter).
Descriptionstring

A short description of the special category in the language specified in the HTTP Accept-Language header in the request.

Messagestring

The warning text automatically added to the ad, in the language specified in the HTTP Accept-Language header in the request (see the section Warnings and age limits in ads in the Help for Yandex.Direct).

ConstantsItem structure (for restrictions on parameter values)
Namestring

Name of the restriction:

  • MaximumAdTextLength — Deprecated. Use MaximumTextAdTextLength.

  • MaximumAdTextWordLength — Maximum number of characters per word in the ad text.

  • MaximumAdTitleLength — Deprecated. Use MaximumTextAdTitleLength.

  • MaximumAdTitleWordLength — Maximum number of characters per word in the ad title.

  • MaximumDynamicTextAdTextLength — Maximum number of characters in the text of a dynamic ad, not counting "narrow" characters.

  • MaximumMobileAppAdTextLength — Maximum number of characters in the text of a mobile app ad.

  • MaximumMobileAppAdTitleLength — Maximum number of characters in the title of a mobile app ad.

  • MaximumNumberOfNarrowCharacters — Maximum number of "narrow" characters in the ad title or text.

  • MaximumSitelinkDescriptionLength — Maximum number of characters in a sitelink description.

  • MaximumSitelinksLength — Maximum number of characters in the combined texts of a set of sitelinks.

  • MaximumSitelinksNumber — Maximum number of sitelinks in a set.

  • MaximumSitelinkTextLength — Maximum number of characters in a sitelink text.

  • MaximumTextAdTextLength — Maximum number of characters in the text of a text and image ad, not counting "narrow" characters.

  • MaximumTextAdTitleLength — Maximum number of characters in the first title of a text and image ad, not counting "narrow" characters.

  • MaximumTextAdTitle2Length — Maximum number of characters in the second title of a text and image ad, not counting "narrow" characters.

Valuestring

The limit value.

CurrenciesItem structure
CurrencystringDesignates the currency (the Currency campaign parameter).
Propertiesarray of ConstantsItem

Name and value of the currency parameter.

ConstantsItem structure
Namestring

Name of the currency parameter:

  • FullName — Name of the currency in the language specified in the HTTP Accept-Language header.
  • BidIncrement — The bid increment.
  • MaximumBid — The maximum CPC bid (technical limitation).
  • MaximumCPM — The maximum CPM bid or price for display ads.
  • MinimumAverageCPA — The minimum value of the average CPA for the AVERAGE_CPA strategy, or the minimum value of the average CPI for the AVERAGE_CPI strategy.
  • MinimumAverageCPC — The minimum value of the average CPC for the AVERAGE_CPC and WEEKLY_CLICK_PACKAGE strategies.
  • MinimumBid — The minimum CPC bid.
  • MinimumCPM — The minimum CPM bid or price for display ads.
  • MinimumDailyBudget — The minimum daily budget for a campaign.
  • MinimumPayment — The minimum payment (without VAT) and the minimum daily budget for a shared account.
  • MinimumTransferAmount — The minimum amount to transfer between campaigns.
  • MinimumWeeklySpendLimit — The minimum weekly budget.

See the examples.

Valuestring

Value of the currency parameter.

Attention. All returned monetary values are whole integers — the result of multiplying the bid or price by 1,000,000.
GeoRegionsItem structure
GeoRegionIdlongID of the region.
GeoRegionNamestring

Name of the region in the language specified in the HTTP Accept-Language header in the request.

GeoRegionTypestringThe type of region: World, Continent, Region, Country, Administrative area, District, City, City district, Village.
ParentIdlong, nillableID of the higher-level region.
MetroStationsItem structure
GeoRegionIdlongID of the region.
MetroStationIdlongID of the metro station (the MetroStationId vCard parameter).
MetroStationNamestringName of the station (in Russian).
OperationSystemVersionsItem structure
OsNamestringName of the operating system.
OsVersionstringVersion of the operating system.
TimeZonesItem structure
TimeZonestringDesignates the time zone (the TimeZone campaign parameter).
TimeZoneNamestringDescription of the time zone in the language specified in the HTTP Accept-Language header in the request.
UtcOffsetintThe offset from UTC in seconds.
SupplySidePlatformsItem structure
TitlestringThe name of an ad exchange.
InterestsItem structure
InterestIdlongID of an app category interest.
ParentIdlongID of the higher-level interest.
Namestring

Name of the interest in the language specified in the HTTP Accept-Language header in the request.

IsTargetableYesNoEnumIndicates whether the interest ID can be used in audience targets.
AudienceCriteriaTypesItem structure
TypestringID of a demographic or behavioral characteristic.
BlockElementstringThe category that this characteristic belongs to:
  • SOCIAL — Gender, age, income.
  • EXTENDED_SOCIAL — Marital status, children, profession.
  • BEHAVIORAL_INDICATORS — Behavioral characteristics.
Namestring

Name of the characteristic in the language specified in the HTTP Accept-Language header in the request.

DescriptionstringDescription of the characteristic in the language specified in the HTTP Accept-Language header in the request.
CanSelectCanSelectEnumWhether all segments for this characteristic can be specified in a user selection rule (for example, you aren't allowed to specify all age groups, but you can specify all professions).
AudienceDemographicProfilesItem structure
IdlongID of a demographic or behavioral segment.
TypestringID of a demographic or behavioral characteristic (the TypeId parameter in the AudienceCriteriaTypes structure).
Namestring

Name of the segment in the language specified in the HTTP Accept-Language header in the request.

DescriptionlongDescription of the segment in the language specified in the HTTP Accept-Language header in the request.
AudienceInterestsItem structure
InterestKeylongID of a user interest.
Idlong

ID of a user interest segment.

The segment ID consists of a prefix indicating the type of interest and the ID of the interest. For example, the InterestKey is 2499001182 (air tickets), and the Id is 102499001182 (short-term interest in air tickets).

ParentIdlongID of the higher-level segment.
Namestring

Name of the segment in the language specified in the HTTP Accept-Language header in the request.

DescriptionlongDescription of the segment in the language specified in the HTTP Accept-Language header in the request.
InterestTypeInterestTypeEnumType of interest: short-term, long-term, or for any period.

Examples

Sample request: getting the currency reference list
{
  "method": "get",
  "params": {
    "DictionaryNames": [ "Currencies" ]
  }
}
Response example
{
  "result": {
    "Currencies": [
      {
        "Currency":"RUB",
        "Properties": [
          { "Name": "FullName",                "Value": "Russian rubles" },
          { "Name": "BidIncrement",            "Value": "100000" },
          { "Name": "MaximumBid",              "Value": "25000000000" },
          { "Name": "MaximumCPM",              "Value": "3000000000" },
          { "Name": "MinimumAverageCPA",       "Value": "900000" },
          { "Name": "MinimumAverageCPC",       "Value": "900000" }, 
          { "Name": "MinimumBid",              "Value": "300000" },
          { "Name": "MinimumCPM",              "Value": "5000000" },
          { "Name": "MinimumDailyBudget",      "Value": "300000000" }, 
          { "Name": "MinimumPayment",          "Value": "1000000000" },  
          { "Name": "MinimumTransferAmount",   "Value": "1000000000" },
          { "Name": "MinimumWeeklySpendLimit", "Value": "300000000" }
        ]
      },
      ...
      {
        "Currency": "EUR",
        "Properties": [
          { "Name": "FullName",                "Value": "euro" },
          { "Name": "BidIncrement",            "Value": "10000" },
          { "Name": "MaximumBid",              "Value": "500000000" },
          { "Name": "MaximumCPM",              "Value": "44000000" },
          { "Name": "MinimumAverageCPA",       "Value": "30000" },
          { "Name": "MinimumAverageCPC",       "Value": "30000" },
          { "Name": "MinimumBid",              "Value": "10000" },
          { "Name": "MinimumCPM",              "Value": "70000" },
          { "Name": "MinimumDailyBudget",      "Value": "10000000" },
          { "Name": "MinimumPayment",          "Value": "15000000" },
          { "Name": "MinimumTransferAmount",   "Value": "15000000" },
          { "Name": "MinimumWeeklySpendLimit", "Value": "10000000" }
        ]
      } 
    ]
  }
}