페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Targeting for ad group

Kakao Moment

Targeting for ad group

This document describes how to use the Targeting for ad group APIs.

Targeting for ad group APIs provide ad group's information for the targeting settings as a list. You can use these APIs to check the required parameter values before you create or edit an ad group.

View city/province

This API enables you to retrieve a list of -si (city) or -do (province) information you can use for region targeting.

Send a GET request with the issued access token in the request header. If the request is successful, this API returns the list of -si (city) or -do (province) information and key values of the corresponding location. You can use the values of description and depth1Name passed in the response for targeting.locations when you create or edit an ad group.

Request
URL
GET /openapi/v4/targetings/location/depth1 HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Response
Name Type Description
- Location[] List of -si (city) or -do (province) information.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth1" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "value": "A",
        "description": "강원도",
        "depth1Name": "강원도",
    },
    {
        "value": "B",
        "description": "경기도",
        "depth1Name": "경기도",
    },
    {
        "value": "C",
        "description": "경상남도",
        "depth1Name": "경상남도",
    },
    ...
]

View city/county/district

This API enables you to retrieve a list of -si (city), -gun (county), or -gu (district) information of a specific location. You can use the information for region targeting when creating or editing an ad group.

Send a GET request with the issued access token in the request header. You must pass the location name you want to search for through the keyword parameter. If the request is successful, this API returns the list of -si (city), -gun (county), or -gu (district) information and key values of the corresponding location. You can use the values of description, depth1Name and depth2Name passed in the response for targeting.depth2Locations when you create or edit an ad group. If you do not pass keyword when you request, the request fails and an error is returned.

Request
URL
GET /openapi/v4/targetings/location/depth2 HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Parameter
Name Type Description Required
keyword String Location you want to know its -si, -gun, or -gu information. O
Response
Name Type Description
- Depth2Location[] List of -si (city), -gun (county), or -gu information.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth2?keyword=서울" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
Response: Success
[
    {
        "value": "I1000",
        "description": "서울특별시 강남구",
        "depth1Name": "서울특별시",
        "depth2Name": "강남구"
    },
    {
        "value": "I1001",
        "description": "서울특별시 강동구",
        "depth1Name": "서울특별시",
        "depth2Name": "강동구"
    },
    ...
]
Response: Fail
HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
       "detailCode": 75029,
       "detailMsg": "조회할 시/군/구 검색어를 입력해 주세요."
    }
}

View neighborhood/town/township

This API enables you to retrieve a list of -dong (neighborhood), -eup (town), or -myeon (townships) information of a specific location. You can use the information for region targeting when creating or editing an ad group.

Send a GET request with the issued access token in the request header. You must pass the location name you want to search for through the keyword parameter. If the request is successful, this API returns the list of -dong, -eup, or -myeon information and key values of the corresponding location. You can use the values of description, depth1Name and depth2Name passed in the response for targeting.depth3Locations when you create or edit an ad group. If you do not pass keyword when you request, the request fails and an error is returned.

Request
URL
GET /openapi/v4/targetings/location/depth3 HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Parameter
Name Type Description Required
keyword String Location you want to know its -dong, -eup, or -myeon information. O
Response
Name Type Description
- Depth3Location[] List of -dong, -eup, or -myeon information.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth3?keyword=논현" \
    -H "Authorization: Bearer {ACCESS_TOKEN}"
Response: Success
[
    {
        "value": "I10000101",
        "description": "서울특별시 강남구",
        "depth1Name": "서울특별시",
        "depth2Name": "강남구",
        "depth3Name" : "논현1동"
    },
    {
        "value": "I10000102",
        "description": "서울특별시 강동구",
        "depth1Name": "서울특별시",
        "depth2Name": "강남구",
        "depth3Name" : "논현2동"
    },
    ...
]
Response: Fail

HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
       "detailCode": 75528,
       "detailMsg": "조회할 동/읍/면 검색어를 입력해 주세요."
    }
}

View categories of Network for placements

This API enables you to retrieve a list of placements.

Send a GET request with the issued access token in the request header. If the request is successful, this API returns the name and code of the sub-categories of the Network placement. You can use the values of code passed in the response for the value of adServingCategories as an array when you create or edit an ad group. You cannot set the Network placement for the Display X Conversion(전환) type of campaign.

Request
URL
GET /openapi/v4/targetings/placement/adServingCategories HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Response
Name Type Description
- NetworkPlacement[] List of the category information for Network placement.
NetworkPlacement
Name Type Description
code String Category code of the Network placement.
When creating or editing an ad group, set the adServingCategories field to code as an array.
In this case, name is not required.
name String Category name of the Network placement.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/placement/adServingCategories" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "code": "IAB16",
        "name": "애완동물"
    },
    {
        "code": "IAB8",
        "name": "식음료"
    },
    {
        "code": "IAB15",
        "name": "과학"
    },
    ...
]

View list of section categories

This API enables you to retrieve a list of section categories you can select when you create or edit an ad group.

You can select a section category only when the campaign type is 'Kakao Bizboard' and placements is set to KAKAO_TALK.

Send a GET request with the issued access token in the request header. If the request is successful, this API returns the list of selectable section categories. You can use the values of code for the value of sectionCategories as an array when creating or editing an ad group.

Request
URL
GET /openapi/v4/targetings/placement/sectionCategories HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Response
Name Type Description
- SectionCategory[] List of section categories.
SectionCategory
Name Type Description
code String Code of section category.
When you create or edit ad group, use this code for the sectionCategories field as an array.
In this case, name is not required.
name String Name of section category.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/placement/sectionCategories" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "code": "KKO99-1",
        "name": "채팅탭에만 노출"
    }
    ...
]

View targetable engagement targets

This API enables you to retrieve a list of engagement targets for custom audience targeting, which you can use as a targeting option when you create or edit an ad group.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the detailed information and status of available engagement targets. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/adGroups/targetings/cohort/availables HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Response
Name Type Description
- CohortAvailable[] List of engagement targets that can be used for custom audience targeting.
CohortAvailable
Name Type Description
id Long Engagement target's ID.
Pass this value through cohortId as the array of targeting.cohortTargetings when creating or editing an ad group.
audienceType String Engagement target's type.
Either DISPLAY or MESSAGE.
When you create or edit an ad group or Audience, you need to use the available Audience type between Display and Message according to its campaign Type X Goal.
adAccountId Long Ad account's ID.
name String Engagement target's name.
baseAds BaseAd[] List of ad response data.
collectDuration Integer Collecting period.
User data collected during this period from today is used for the ad targeting.
If no one responded to your ad during this period, data may not exist even though you have run ads before.
status String Status of target population.
One of the followings:
WAITING: Preparing for extracting target population
AVAILABLE_ERROR: Error in extracting target population
AVAILABLE: Target population has been extracted from a customer file
SEED_NOT_ENOUGH: Insufficient target population
DELETE: Deleted or deleting
ERROR: Other errors
createdDate String Date and time of creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time of modification in yyyy-MM-dd'T'HH:mm:ss format.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/cohort/availables" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "adAccountId": 1234,
        "id": 1,
        "audienceType": "DISPLAY",
        "name": "first_ad_response_target",
        "baseAds": [
            {
                "campaign": {
                    "id": 5678,
                    "name": "first_campaign",
                    "campaignTypeGoal": {
                        "campaignType": "DISPLAY",
                        "goal": "VISITING"
                    }
                },
                "adGroup": {
                    "id": 9012,
                    "name": "first_ad_group"
                },
                "operation": "MINUS",
                "firstIndicator": "OPEN",
                "secondIndicator": "CLICK"
            }
        ],
        "collectDuration": 90,
        "status": "AVAILABLE",
        "createdDate": "2018-02-07 10:46:12",
        "lastModifiedDate": "2020-07-07 19:15:38"
    },
    {
        "adAccountId": 1234,
        "id": 2,
        "audienceType": "DISPLAY",
        "name": "second_ad_response_target",
        "baseAds": [
            {
                "campaign": {
                    "id": 5678,
                    "name": "second_campaign",
                    "campaignTypeGoal": {
                        "campaignType": "DISPLAY",
                        "goal": "CONVERSION"
                    }
                },
                "adGroup": {
                    "id": 9012,
                    "name": "second_ad_group"
                },
                "operation": "ONLY",
                "firstIndicator": "CONVERSION"
            }
        ],
        "collectDuration": 90,
        "status": "AVAILABLE",
        "createdDate": "2020-01-01 00:00:00",
        "lastModifiedDate": "2020-01-01 00:00:00"
    }
]

View targetable Pixel & SDK events

This API enables you to retrieve a list of Pixel & SDK events for custom audience targeting, which you can use as a targeting option when you create or edit an ad group.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. You must pass a tracker ID (trackID) and a targeting period (dimensions) when you request. If the request is successful, this API returns the list of tracker information about each event in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/adGroups/targetings/trackers/eventCreatables/{trackId} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
trackId String Tracker ID.
Use the id that is retrieved through the Viewing Pixel & SDK API.
O
dimensions Set of Dimension Targeting period. O
Response
Name Type Description
- PixelAndSdkEvent[] List of Pixel & SDK events that can be used for custom audience targeting.
PixelAndSdkEvent
Name Type Description
eventCode String Event code.
eventName String Event name.
eventExtraName String Additional description for the event.
trackRuleId String Tracker information ID.
trackRule TrackRule Tracker rule.
population Integer Collected target population.
lastEventDate String Date and time of event confirmed in yyyy-MM-dd'T'HH:mm:ss format.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/trackers/eventCreatables/{trackId}?dimensions=ONE_MONTH,TWO_MONTHS" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "trackRule": {
            "trackRuleId": "*",
            "trackId": "3830610710806837838",
            "eventCode": "PageView",
            "name": "visit",
            "ruleSetStr": "[]"
        },
        "lastEventDate": "2019.10.16 19:36",
        "eventCode": "PageView",
        "eventName": "visit",
        "trackRuleId": "*",
        "population": 15290918,
        "eventExtraName": ""
    }
]

View list of targetable customer files

This API enables you to retrieve a list of customer files you can use for the targeting option when you create or edit an ad group.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the list of customer files in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/adGroups/targetings/customerFiles/availables HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Response
Name Type Description
- CustomerFile[] List of customer files information that can be used for custom audience targeting.
CustomerFile
Name Type Description
id Long Customer file's ID.
adAccountId Long Ad account's ID.
name String Customer file's name.
adidListKey String Customer file's registration key.
status String Status.
One of the followings:
WAITING: Waiting for extracting target population
COMPLETE: Target population has been extracted from a customer file
DELETE: Deleted or deleting
ERROR: Other abnormal cases
populationScore String Target population.
The number of Kakao users extracted from the registered customer file.
If a customer file's status is WAITING, you cannot use the customer file for targeting since population has not been extracted yet.
Population is extracted within 6 hours after a customer file is registered.
ready Boolean Whether it is ready or not.
createdDate String Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time of target modification in yyyy-MM-dd'T'HH:mm:ss format.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/customerFiles/availables" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": 1,
        "adAccountId": 1234,
        "name": "first_customer file",
        "adidListKey": "123456789abcdefghijklmn",
        "status": "COMPLETE",
        "populationScore": 100,
        "ready": true,
        "createdDate": "2020-01-01 00:00",
        "lastModifiedDate": "2020-01-01 00:00"
    }
]

View list of targetable Kakao Talk Channels

This API enables you to retrieve a list of Kakao Talk Channel information you can use for the targeting option when you create or edit an ad group.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the retrieved Kakao Talk Channel information. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/adGroups/targetings/talkChannels/availables HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Response
Name Type Description
- ChannelProfile[] List of Kakao Talk Channel profile that can be used for custom audience targeting.
ChannelProfile
Name Type Description
id String Kakao Talk Channel's profile ID.
name String Kakao Talk Channel's profile name.
searchId String Kakao Talk Channel's name used for search.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannels/availables" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": "_xbHxd",
        "name": "first_friend",
        "searchId": "first_friend"
    },
    {
        "id": "_ZQxd",
        "name": "second_friend",
        "searchId": "second_friend"
    }
]

View list of targetable Kakao Login users

This API enables you to retrieve a list of Kakao Login users you can use for the targeting option when you create or edit an ad group.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. You can use id that is passed in the response for Kakao Login user targeting when creating or editing an ad group. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/adGroups/targetings/syncProfiles/availables HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Response
Name Type Description
- SyncProfile[] List of Kakao Login users that can be used for custom audience targeting.
SyncProfile
Name Type Description
id String Kakao Talk Channel's profile ID.
name String Kakao Talk Channel's profile name.
searchId String Kakao Talk Channel's name used for search.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/syncProfiles/availables" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": "_XLd",
        "name": "first_friend_with_profile",
        "searchId": "now_profile_exist"
    },
    {
        "id": "_cWn",
        "name": "second_friend_with_profile",
        "searchId": "after_profile_exist"
    }
]

See more