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 */
  }
}
Parameter Type Description Required
Params structure (for JSON) / GetRequest (for SOAP)
DictionaryNames array of DictionaryNameEnum Names 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 */
    }, ... ]
  }
}
Parameter Type Description
Result structure (for JSON) / GetResponse (for SOAP)
AdCategories array of AdCategoriesItem

Special categories of advertised products and services.

See the section Special category.

Constants array of ConstantsItem Restrictions on parameter values.
Currencies array of CurrenciesItem Currency exchange rates, currency parameters, and restrictions.
GeoRegions array of GeoRegionsItem Regions.
MetroStations array of MetroStationsItem Metro stations (only for Moscow, Saint Petersburg, and Kiev).
OperationSystemVersions array of OperationSystemVersionsItem Versions of operating systems for advertising mobile apps.
ProductivityAssertions array of ProductivityAssertionsItem This parameter is obsolete and is not returned.
TimeZones array of TimeZonesItem Time zones.
SupplySidePlatforms array of SupplySidePlatformsItem Ad exchanges (SSPs).
Interests array of InterestsItem Interests in mobile app categories.
AudienceCriteriaTypes array of AudienceCriteriaTypesItem Demographic and behavioral characteristics.
AudienceDemographicProfiles array of AudienceDemographicProfilesItem Segments based on demographic and behavioral characteristics for targeting by user profile.
AudienceInterests array of AudienceInterestsItem Segments based on user interests for targeting by user profile.
AdCategoriesItem structure
AdCategory string Designates a special category (the AdCategories ad parameter).
Description string

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

Message string

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)
Name string

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.

Value string

The limit value.

CurrenciesItem structure
Currency string Designates the currency (the Currency campaign parameter).
Properties array of ConstantsItem

Name and value of the currency parameter.

ConstantsItem structure
Name string

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.

Value string

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
GeoRegionId long ID of the region.
GeoRegionName string

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

GeoRegionType string The type of region: World, Continent, Region, Country, Administrative area, District, City, City district, Village.
ParentId long, nillable ID of the higher-level region.
MetroStationsItem structure
GeoRegionId long ID of the region.
MetroStationId long ID of the metro station (the MetroStationId vCard parameter).
MetroStationName string Name of the station (in Russian).
OperationSystemVersionsItem structure
OsName string Name of the operating system.
OsVersion string Version of the operating system.
TimeZonesItem structure
TimeZone string Designates the time zone (the TimeZone campaign parameter).
TimeZoneName string Description of the time zone in the language specified in the HTTP Accept-Language header in the request.
UtcOffset int The offset from UTC in seconds.
SupplySidePlatformsItem structure
Title string The name of an ad exchange.
InterestsItem structure
InterestId long ID of an app category interest.
ParentId long ID of the higher-level interest.
Name string

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

IsTargetable YesNoEnum Indicates whether the interest ID can be used in audience targets.
AudienceCriteriaTypesItem structure
Type string ID of a demographic or behavioral characteristic.
BlockElement string The category that this characteristic belongs to:
  • SOCIAL — Gender, age, income.
  • EXTENDED_SOCIAL — Marital status, children, profession.
  • BEHAVIORAL_INDICATORS — Behavioral characteristics.
Name string

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

Description string Description of the characteristic in the language specified in the HTTP Accept-Language header in the request.
CanSelect CanSelectEnum Whether 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
Id long ID of a demographic or behavioral segment.
Type string ID of a demographic or behavioral characteristic (the TypeId parameter in the AudienceCriteriaTypes structure).
Name string

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

Description long Description of the segment in the language specified in the HTTP Accept-Language header in the request.
AudienceInterestsItem structure
InterestKey long ID of a user interest.
Id long

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).

ParentId long ID of the higher-level segment.
Name string

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

Description long Description of the segment in the language specified in the HTTP Accept-Language header in the request.
InterestType InterestTypeEnum Type 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" }
        ]
      } 
    ]
  }
}