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.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { /* params */
    "DictionaryNames": [( "Currencies"
                        | "MetroStations"
                        | "GeoRegions"
                        | "GeoRegionNames"
                        | "TimeZones"
                        | "Constants"
                        | "AdCategories"
                        | "OperationSystemVersions"
                        | "ProductivityAssertions"
                        | "SupplySidePlatforms"
                        | "Interests"
                        | "AudienceCriteriaTypes"
                        | "AudienceDemographicProfiles"
                        | "AudienceInterests"
                        | "FilterSchemas"), ... ] /* 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 */
    }, ... ],
    "GeoRegionNames": [{  /* GeoRegionNamesItem */
      "GeoRegionId": (long), /* required */
      "GeoRegionName": (string), /* required */
      "GeoRegionType": (string), /* required */
    }, ... ],
    "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), /* nillable */
      "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 */
    }, ... ],
    "FilterSchemas": [{ /* FilterSchemasItem */
      "Name": (string), /* required */
      "Fields": [{ /* required */
        "Name": (string), /* required */
        "Type": ("Enum", "Number", "String"), /* required */
        "EnumProps": {
          "Values": { /* required */
            "Items": [(string)] /* required */
          },
        },
        "NumberProps": {
          "Min": (decimal), /* required */
          "Max": (decimal), /* required */
          "Precision": (integer) /* required */
        },
        "StringProps": {
          "MaxLength": (integer), /* required */
          "MinLength": (integer) /* required */
        },
        "Operators": [{ /* required */
          "MaxItems": (integer), /* required */
          "Type": ("CONTAINS_ANY" | "EQUALS_ANY" | "EXISTS" | "GREATER_THAN" | "IN_RANGE" | "LESS_THAN" | "NOT_CONTAINS_ALL") /* 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 available for targeting.
`GeoRegionNames`	array of GeoRegionNamesItem	Directory of names of 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.
FilterSchemas	array of FilterSchemasItem	Names of schemas for creating filters.
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 ads in the Yandex Direct Help).
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 & Image ad, not counting "narrow" characters. MaximumTextAdTitleLength is the maximum number of characters allowed in the first title of a Text & Image ad, excluding “narrow” characters. MaximumTextAdTitle2Length is the maximum number of characters allowed in the second title of a Text & Image ad, excluding “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 (for currency parameters)
`Name`	string	Name of the currency parameter: FullName — Name of the currency in the language specified in the HTTP Accept-Language header. AutobudgetAvgCpaWarning — An average CPA. BidIncrement — The bid increment. MaxAutobudget — The maximum weekly autobudget. MaximumAverageCPV — The maximum average CPV for the CP_AVERAGE_CPV and WB_AVERAGE_CPV strategies. MaximumBid — The maximum CPC bid (technical limitation). MaximumCPM — The maximum CPM bid or price for display ads. MaxDailyBudgetForPeriod: The maximum budget for a fixed period. MaximumPayForConversionCPA — The maximum CPA for the PAY_FOR_CONVERSION, PAY_FOR_CONVERSION_PER_CAMPAIGN, and PAY_FOR_INSTALL strategies. MinimumAccountDailyBudget — The minimum daily budget of the shared account. MinimumAverageCPA — The minimum value of the average CPA for the AVERAGE_CPA strategy, the minimum value of the average CPI for the AVERAGE_CPI strategy, or the minimum CPA for the PAY_FOR_CONVERSION strategy. MinimumAverageCPC — The minimum value of the average CPC for the AVERAGE_CPC and WEEKLY_CLICK_PACKAGE strategies. MinimumAverageCPV — The minimum average CPV for the CP_AVERAGE_CPV and WB_AVERAGE_CPV strategies. MinimumBid — The minimum CPC bid. MinCpcCpaPerformance — A minimum CPC/CPA for smart banners. MinimumCPM — The minimum CPM bid or price for display ads. MinimumDailyBudget — The minimum daily budget for a campaign. MinDailyBudgetForPeriod: A minimum budget for a fixed period. MinimumPayment — The minimum payment (without VAT). MinimumPayForConversionCPA — The minimum CPA for the PAY_FOR_CONVERSION, PAY_FOR_CONVERSION_PER_CAMPAIGN, and PAY_FOR_INSTALL strategies. MinimumTransferAmount — The minimum amount to transfer between campaigns. MinimumWeeklySpendLimit — The minimum weekly budget. See the examples.
`Value`	string	Value of the currency parameter. Alert All returned monetary values are integers — the result of multiplying the bid or CPC 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.
GeoRegionNamesItem 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.
MetroStationsItem structure
`GeoRegionId`	long	ID of the region.
`MetroStationId`	long	ID of the subway 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, nillable	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 "Type" 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`	string	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`	string	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.
FilterSchemasItem structure
`Name`	string	The name of the schema for creating filters.
`Fields`	array of FilterSchemaItemFields	Schema parameters.
FilterSchemasItemFields structure (for filter creation schema parameters)
`Name`	string	The name of the parameter.
`Type`	FieldTypeEnum	Parameter type: Enum, Number, String.
EnumProps	EnumFieldStructure	Structure of the Enum type parameter.
NumberProps	NumberFieldStructure	Structure of the Number type parameter.
StringProps	StringFieldStructure	Structure of the String type parameter.
Operators	array of OperatorStructure	Operators.
EnumFieldStructure structure (for the structure of the Enum type parameter)
Values	EnumFieldStructureItem	Structure of values of the Enum type parameter.
EnumFieldStructureItem structure (for the values of the Enum type parameter)
Items	array of strings	Array of values.
NumberFieldStructure structure (for the structure of the Number type parameter)
Min	decimal	Minimum value.
Max	decimal	Maximum value.
Precision	integer	Precision.
StringFieldStructure structure (for the structure of the String type parameter)
MaxLength	integer	The maximum length of the returned string.
MinLength	integer	The minimum length of the returned string.
OperatorStructure structure (for the structure of the operator)
MaxItems	integer	The maximum number of elements.
Type	OperatorEnum	Operator: CONTAINS_ANY, EQUALS_ANY, EXISTS, GREATER_THAN, IN_RANGE, LESS_THAN, NOT_CONTAINS_ALL.

Examples

Sample request: getting the currency reference list

{
  "method": "get",
  "params": {
    "DictionaryNames": [ "Currencies" ]
  }
}

Response example

{
  "result": {
    "Currencies": [
      {
        "Currency":"RUB",
        "Properties": [
          { "Name": "FullName",                   "Value": "российские рубли" },
          { "Name": "AutobudgetAvgCpaWarning",    "Value": "XXXX" },
          { "Name": "BidIncrement",               "Value": "100000" },
          { "Name": "MaxAutobudget",              "Value": "XXXX" },
          { "Name": "MaximumBid",                 "Value": "25000000000" },
          { "Name": "MaximumCPM",                 "Value": "3000000000" },
          { "Name": "MaxDailyBudgetForPeriod",    "Value": "XXXX" },
          { "Name": "MaximumPayForConversionCPA", "Value": "5000000000" },
          { "Name": "MinimumAverageCPA",          "Value": "900000" },
          { "Name": "MinimumAverageCPC",          "Value": "900000" },
          { "Name": "MinimumBid",                 "Value": "300000" },
          { "Name": "MinCpcCpaPerformance",       "Value": "XXXX" },
          { "Name": "MinimumCPM",                 "Value": "5000000" },
          { "Name": "MinimumDailyBudget",         "Value": "300000000" },
          { "Name": "MinDailyBudgetForPeriod",    "Value": "XXXX" },
          { "Name": "MinimumPayment",             "Value": "300000000" },
          { "Name": "MinimumPayForConversionCPA", "Value": "900000" },
          { "Name": "MinimumTransferAmount",      "Value": "1000000000" },
          { "Name": "MinimumWeeklySpendLimit",    "Value": "300000000" }
        ]
      },
      ...
      {
        "Currency": "EUR",
        "Properties": [
          { "Name": "FullName",                   "Value": "евро" },
          { "Name": "AutobudgetAvgCpaWarning",    "Value": "XXXX" },
          { "Name": "BidIncrement",               "Value": "10000" },
          { "Name": "MaxAutobudget",              "Value": "XXXX" },
          { "Name": "MaximumBid",                 "Value": "500000000" },
          { "Name": "MaximumCPM",                 "Value": "44000000" },
          { "Name": "MaxDailyBudgetForPeriod",    "Value": "XXXX" },
          { "Name": "MaximumPayForConversionCPA", "Value": "170000000" },
          { "Name": "MinimumAverageCPA",          "Value": "30000" },
          { "Name": "MinimumAverageCPC",          "Value": "30000" },
          { "Name": "MinimumBid",                 "Value": "10000" },
          { "Name": "MinCpcCpaPerformance",       "Value": "XXXX" },
          { "Name": "MinimumCPM",                 "Value": "70000" },
          { "Name": "MinimumDailyBudget",         "Value": "10000000" },
          { "Name": "MinDailyBudgetForPeriod",    "Value": "XXXX" },
          { "Name": "MinimumPayment",             "Value": "15000000" },
          { "Name": "MinimumPayForConversionCPA", "Value": "30000" },
          { "Name": "MinimumTransferAmount",      "Value": "15000000" },
          { "Name": "MinimumWeeklySpendLimit",    "Value": "10000000" }
        ]
      }
    ]
  }
}

Was the article helpful?

Dictionaries: getting reference lists

getGeoRegions