后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载导读TagFeedResponseStoryLocationsItem是 instagram-private-apiNodeJS Instagram 私有 API SDK中用于描述标签话题页hashtagStory Tray 内位置贴纸location sticker的响应数据模型。在 TypeScript 中它被定义为TagFeedResponse的嵌套接口承载每个位置贴纸在故事画布上的坐标、尺寸、旋转角与层级信息并内嵌一个TagFeedResponseLocation地点对象。读完本文你将掌握该接口全部字段的含义与数据类型、它在TagFeed标签故事流中的实际 JSON 形态以及如何通过StickerBuilder在发布端构造与之对称的位置贴纸数据实现读取标签页故事 → 解析地点贴纸 → 结构化使用地点信息的完整链路。一、接口定位标签页 Story Tray 的贴纸清单TagFeedResponseStoryLocationsItem不是孤立的数据类型它隶属于标签话题 Feed 的整体响应结构。在 tag.feed.response.ts 中TagFeedResponse顶层接口定义了标签页响应的骨架export interface TagFeedResponse { ranked_items: TagFeedResponseRankedItemsItem[]; items: TagFeedResponseItemsItem[]; num_results: number; next_max_id: string; more_available: boolean; auto_load_more_enabled: boolean; story: TagFeedResponseStory; status: string; }其中story: TagFeedResponseStory是标签页顶部的 Story Tray若干账号的最新快拍合集其items: TagFeedResponseItemsItem[]中的每一个快拍条目TagFeedResponseItemsItem都可能携带一组贴纸数据其中就包括位置贴纸export interface TagFeedResponseItemsItem { // ... 媒体基础字段pk、media_type、image_versions2 等 is_reel_media?: boolean; expiring_at?: number; story_hashtags?: TagFeedResponseStoryHashtagsItem[]; creative_config?: TagFeedResponseCreative_config; reel_mentions?: TagFeedResponseReelMentionsItem[]; story_locations?: TagFeedResponseStoryLocationsItem[]; // ← 本文主角 // ... }也就是说一个快拍条目下通常会有话题贴纸数组story_hashtags、提及贴纸数组reel_mentions、位置贴纸数组story_locations三类贴纸清单TagFeedResponseStoryLocationsItem就是其中位置贴纸清单的单个元素类型最终由 tag.feed.response.ts#L274-L284 定义。数据来源链路该响应来自TagFeed对 Instagram 私有接口/api/v1/feed/tag/{tag}/的请求。在 tag.feed.ts 中可以看到请求参数包含rank_token由基类Feed用Chance生成的 GUID见 core/feed.ts和分页游标max_idasync request() { const { body } await this.client.request.sendTagFeedResponse({ url: /api/v1/feed/tag/${encodeURI(this.tag)}/, qs: { rank_token: this.rankToken, max_id: this.nextMaxId, }, }); this.state body; return body; }TagFeed.state会把more_available与next_max_id写入内部状态用于items$可观测流的持续翻页拉取参见 core/feed.ts 的 retry/分页逻辑因此标签页的快拍及其贴纸可以通过分页接口全部枚举出来。二、接口全景字段速览对照 TagFeedResponseStoryLocationsItem.md 文档该接口共 9 个属性逐一对应源码 tag.feed.response.ts#L274-L284属性类型语义xnumber \| string贴纸中心点水平坐标归一化ynumber \| string贴纸中心点垂直坐标归一化znumber图层层级z 序widthnumber \| string贴纸宽度占画布比例heightnumber \| string贴纸高度占画布比例rotationnumber旋转角度度is_pinnednumber是否被固定1/0 布尔量的数值形式is_hiddennumber是否被隐藏1/0 布尔量的数值形式locationTagFeedResponseLocation内嵌的地点对象名称、地址、经纬度、POI ID 等三、字段详解从坐标到地点对象3.1 几何定位字段x、y、zx: number | string— 贴纸在画布上的水平位置。在 instagram-private-api 的贴纸体系中坐标采用归一化坐标系x、y的取值范围为 010.5代表画布正中央。这一点可以从发布端基类InstaSticker的默认值与定位方法得到印证见 insta-sticker.tspublic x: number 0.0; public y: number 0.0; public center(): this { this.x 0.5; this.y 0.5; return this; }响应字段同时声明为number | string从类型设计上可以推断Instagram 服务端在不同场景下可能返回数字或字符串形式的坐标SDK 因此用联合类型保持对两种序列化形态的兼容。z: number— 图层 z 序。数字越大越靠前显示。发布端InstaSticker.moveForward(layers)/moveBackwards(layers)正是通过增减z值来调整贴纸前后遮挡关系insta-sticker.ts。3.2 尺寸与旋转width、height、rotationwidth/height: number | string— 贴纸占故事画布的宽高比例归一化同样存在number | string联合类型。发布端默认值可参考LocationSticker的默认宽高为width 0.47、height 0.111见 location.sticker.ts即位置贴纸默认横向占据画布的约 47% 宽、11% 高。rotation: number— 贴纸旋转角度单位是度degree。发布端rotateDeg(deg)方法会执行deg % 360.0归一化insta-sticker.ts因此响应中的取值通常落在 0360 区间。3.3 显示状态is_pinned、is_hiddenis_pinned: number— 贴纸是否被钉住。在类型定义中它是number而非boolean实际取值遵循 Instagram 序列化约定1表示是0表示否。is_hidden: number— 贴纸是否处于隐藏状态例如用户在发布后手动隐藏了该贴纸同样是1/0数值。3.4 核心业务字段location: TagFeedResponseLocationlocation是整个贴纸条目的灵魂——它承载了该贴纸对应的真实地点信息。其定义位于 tag.feed.response.ts#L84-L94export interface TagFeedResponseLocation { pk: number | string; // 地点的唯一主键IG location id name: string; // 地点显示名称 address: string; // 详细地址 city: string; // 城市 short_name: string; // 短名称如品牌名、街区简称 lng: number | string; // 经度 lat: number | string; // 纬度 external_source: string; // 外部数据源标识如 facebook_places facebook_places_id: string | number; // Facebook Places 的地点 ID }各字段用途pk可用来在后续请求中定位该地点例如结合locationSearch反查地点详情name/address/city/short_name是可直接展示给终端用户的地点文本信息lat/lng提供了贴纸地点的精确经纬度可用于地图渲染、距离计算或 POI 聚合external_source与facebook_places_id说明了该 POI 的底层数据来源通常是 Facebook Places 数据库这在做地点去重、关联商业 POI 时非常关键。四、发布与读取的对称关系StickerBuilder 如何生成同构数据TagFeedResponseStoryLocationsItem描述的是读取侧服务端响应的位置贴纸形态而在发布侧instagram-private-api 用StickerBuilder.location()构造完全同构的数据二者在字段语义上一一对应。4.1 发布侧LocationSticker与StoryLocation发布位置贴纸需要两层对象贴纸几何对象StoryLocation继承StorySticker基类media.configure-story.options.ts#L71-L77拥有x、y、width、height、rotation等几何字段并附加is_sticker: boolean与location_id: stringexport interface StorySticker { x: number; y: number; width: number; height: number; rotation: number; } export interface StoryLocation extends StorySticker { is_sticker: boolean; location_id: string; }可以看到发布侧的location_id正是读取侧TagFeedResponseLocation.pk的输入来源——贴纸的地点身份在两端是同一 ID。贴纸构造器LocationStickerlocation.sticker.ts它确定了贴纸的唯一标识与序列化键名export class LocationSticker extends InstaSticker { public locationId: string; width 0.47; height 0.111; get id(): string { return location_sticker_vibrant; } get key(): string { return story_locations; // ← 与响应字段 story_locations 同名 } }StickerBuilder.location()sticker-builder.ts#L82-L84负责把普通配置对象转换成LocationSticker实例而StickerBuilder.build()sticker-builder.ts#L30-L52会把贴纸按key分组、JSON 序列化并聚合出story_sticker_ids——这正是configureToStory需要的story_locations表单载荷。4.2 配置项约束geotag_enabled与坐标联动在 media.configure-story.options.ts 中有两条明确的注释约束// if this is set, the geotag has to be set! story_locations?: [StoryLocation] | string; geotag_enabled?: 1 | 0; posting_latitude?: string; posting_longitude?: string; media_latitude?: string; media_longitude?: string;设置story_locations时必须同时开启geotag_enabled 1并携带经纬度四项参数否则服务端会拒绝配置。这一点在发布服务中有完整的实现印证——publish.service.ts#L337-L347if (typeof options.location ! undefined) { const { latitude, longitude } options.location; configureOptions.geotag_enabled 1; configureOptions.posting_latitude latitude; configureOptions.posting_longitude longitude; configureOptions.media_latitude latitude; configureOptions.media_longitude longitude; configureOptions.story_locations [options.location.sticker]; configureOptions.mas_opt_in NOT_PROMPTED; }其中options.location的类型为PostingStoryLocationStickerposting.options.ts#L52-L55由latitude、longitude与sticker: StoryLocation三部分组成。4.3 序列化stringifyStoryStickers在最终提交configureToStory前media.repository.ts#L401-L419 的stringifyStoryStickers会对非字符串数组的贴纸数据做JSON.stringifyconst serialize (obj: any | undefined) { if (typeof obj ! undefined Array.isArray(obj) obj.length 0 typeof obj[0] ! string) { return JSON.stringify(obj); } return obj; }; form.story_hashtags serialize(form.story_hashtags); form.story_locations serialize(form.story_locations); // ... 其余贴纸字段同理这说明服务端收到的story_locations是 JSON 字符串而TagFeedResponse返回的story_locations则是反序列化后的对象数组——两端通过同一字段名story_locations完成了数据的闭环。五、实战读取标签页故事中的位置贴纸综合以上链路读取一个标签页 Story Tray 中所有位置贴纸的完整示例import { IgApiClient } from ../src; import { TagFeed } from ../src/feeds; const ig new IgApiClient(); ig.state.generateDevice(process.env.IG_USERNAME); await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); const tagFeed: TagFeed ig.feed.tag(foodie); // 话题标签 const story await tagFeed.request(); // TagFeedResponse // story.items 是该标签页 Story Tray 的快拍列表 for (const item of story.items) { // 位置贴纸是可选项item.story_locations?: TagFeedResponseStoryLocationsItem[] if (!item.story_locations || item.story_locations.length 0) { continue; } for (const sticker of item.story_locations) { const { location } sticker; console.log({ mediaId: item.id, stickerGeometry: { x: sticker.x, y: sticker.y, z: sticker.z, width: sticker.width, height: sticker.height, rotation: sticker.rotation, pinned: sticker.is_pinned, hidden: sticker.is_hidden, }, place: { pk: location.pk, name: location.name, address: location.address, city: location.city, shortName: location.short_name, coordinates: { lat: location.lat, lng: location.lng }, externalSource: location.external_source, facebookPlacesId: location.facebook_places_id, }, }); } }5.1 结合locationSearch反查地点发布侧示例 upload-story.example.ts 展示了如何通过地点搜索接口获取真实地点 ID 来构造贴纸.add( StickerBuilder.location({ locationId: (await ig.locationSearch.index(13, 37)).venues[0].external_id, }), )locationSearch.index(lat, lng)返回候选地点列表取external_id作为locationId。该external_id与读取侧TagFeedResponseLocation.pk/facebook_places_id体系同源可以在搜索地点 → 发布位置贴纸 → 读取他人故事中的地点贴纸之间建立一致的地点主键映射。六、边界情况与注意事项字段可选性story_locations在TagFeedResponseItemsItem中定义为可选属性story_locations?: TagFeedResponseStoryLocationsItem[]见 tag.feed.response.ts#L185。并非每个标签快拍都带有位置贴纸访问前务必做空值判断或使用?.与?? []防御式取值。数值联合类型x、y、width、height是number | stringlocation.pk、lat、lng、facebook_places_id同理。做坐标运算或数值比较时建议先Number()转换避免字符串拼接导致结果异常。数值型布尔量is_pinned、is_hidden是number而非boolean判断时用 1/ 0而不是直接当成 truthy 布尔值0在 JS 中是 falsy但2等意外值也可能出现。is_reel_media前置条件story_locations只出现在快拍类条目上is_reel_media: true的条目普通时间线帖子items/ranked_items中的非快拍媒体不会携带该字段。Direct Story 不支持贴纸在发布侧publish.service.ts#L302-L315 明确注释 directThread no stickers supported——当threadIds/recipientUsers存在时configure_mode 2且贴纸配置被忽略。这与读取侧逻辑一致只有发布到 Story Trayconfigure_mode 1的内容才会在TagFeed响应中出现贴纸数据。同构接口族TagFeedResponseStoryLocationsItem并非唯一的位置贴纸模型。在 user-story.feed.response.ts、list-reel-media-viewer.feed.response.ts、reels-tray.feed.response.ts、location.repository.story.response.ts 等响应文件中也存在结构相近的StoryLocationsItem类型但各自绑定不同的响应上下文用户主页故事、快拍查看者列表、Reels Tray、地点故事。如需通用处理可依据本接口的几何 location双段结构设计统一的解析器。七、小结TagFeedResponseStoryLocationsItem是 instagram-private-api 中标签页故事流位置贴纸的标准数据契约读取侧通过TagFeed请求/api/v1/feed/tag/{tag}/在story.items[].story_locations[]中取得贴纸的归一化几何信息x/y/z/width/height/rotation、显示状态is_pinned/is_hidden与完整地点对象TagFeedResponseLocation发布侧通过StickerBuilder.location({ locationId })ig.publish.story({ location })构造同构数据需满足geotag_enabled1与经纬度四参数联动的约束闭环价值两端的location_id与location.pk同源使得地点搜索 → 贴纸发布 → 标签故事采集 → 地点聚合分析可以在同一个 SDK 内完成适用于地点打卡统计、POI 热度分析、地图聚合展示等场景。如需深入阅读接口文档与源码可参考接口文档TagFeedResponseStoryLocationsItem.md含各字段 Defined in 行号内嵌地点对象TagFeedResponseLocation.md源码定义tag.feed.response.ts标签 Feed 请求tag.feed.ts发布实现publish.service.ts、media.repository.ts贴纸构造器sticker-builder.ts、location.sticker.ts、insta-sticker.ts配置类型media.configure-story.options.ts完整示例upload-story.example.ts赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐OWASP CheatSheetSeries 之 CI/CD 安全速查表从流水线加固到供应链防护的完整实践指南OWASP CheatSheetSeries 之 CI/CD 安全速查表从流水线加固到供应链防护的完整实践指南 CI/CD 流水线已成为现代软件交付的核心基础后端instagram-private-api 响应接口 LocationRepositoryStoryResponseReelMentionsItem 全解析位置 Story 中 提及贴纸的数据结构instagram private api 响应接口 LocationRepositoryStoryResponseReelMentionsItem 全解析位后端instagram-private-api 中 ReelsMediaFeedResponseStoryPollsItem 接口详解解析 Reels/Story 投票贴纸的响应结构instagram private api 中 ReelsMediaFeedResponseStoryPollsItem 接口详解解析 Reels/Story后端上一篇CodeIgniter 4 版本解读4.0.4 的破坏性变更、新命令与增强项全解析下一篇A-Tune-UI未来路线图openEuler生态系统中的性能优化愿景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考