phone-location-lookup

name	phone-location-lookup
description	根据手机号查询归属地（省份-城市）、原运营商及是否为虚拟运营商，适用于风控校验、用户画像、客服辅助等场景。
license	MIT

能力概述

通过手机号实时查询号码归属地信息，直连三大运营商数据源，非缓存，支持携号转网状态识别。

• Endpoint：POST https://app-bo4w33bsdqm9-api-ELbWz8OmB58Y-gateway.appmiaoda.com/mobile/area
• 核心参数：mobile_number（手机号，查询参数传递）
• 响应格式：JSON，返回归属地省市、原运营商、是否虚拟运营商
• 适用场景：风控校验、用户画像补全、客服辅助、号码信息识别

响应示例：

{
  "code": 200,
  "taskNo": "69564903663951243279",
  "data": {
    "area": "江苏-南通",
    "originalIsp": "电信",
    "isVirtuallyIsp": 1
  }
}

生成期用法（Agent 直接调用）

traefik: true → platform_managed，密钥由平台注入，从 process.env["INTEGRATIONS_API_KEY"] 读取。

注意：所有参数通过 URL Query 参数传递，请求体为空。

const apiKey = process.env["INTEGRATIONS_API_KEY"]!; // platform_managed：密钥由平台注入

/**
 * 查询手机号归属地、原运营商及是否为虚拟运营商。
 * @param mobileNumber - 手机号，例如：13800138000
 * @returns 包含 area、originalIsp、isVirtuallyIsp 的对象
 */
async function queryMobileLocation(
  mobileNumber: string
): Promise<{ area: string; originalIsp: string; isVirtuallyIsp: number }> {
  const url = new URL("https://app-bo4w33bsdqm9-api-ELbWz8OmB58Y-gateway.appmiaoda.com/mobile/area");
  url.searchParams.set("mobile_number", mobileNumber);

  const response = await fetch(url.toString(), {
    method: "POST",
    headers: {
      "Content-Type": "application/json;charset=UTF-8",
      "X-Gateway-Authorization": `Bearer ${apiKey}`,
    },
  });

  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);

  const json = await response.();
   (json. !== )   ();

   json.;
}


 result =  ();
.(result.);          
.(result.);   
.(result.); 

生成后用法（应用内通过 Edge Function 调用）

Edge Function

// edge-functions/phone-location-lookup.ts
import { serve } from "https://deno.land/std/http/server.ts";

serve(async (req: Request): Promise<Response> => {
  if (req.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }

  // --- 解析客户端请求 ---
  let mobileNumber: string;
  try {
    const body = await req.json();
    mobileNumber = body.mobile_number;
    if (!mobileNumber) throw new Error("Missing mobile_number");
  } catch {
    return new Response(JSON.stringify({ error: "Invalid request body" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  // --- 注入平台密钥（严禁暴露到前端） ---
  const apiKey = Deno.env.get();
   (!apiKey) {
      (.({ :  }), {
      : ,
      : { :  },
    });
  }

  
   upstreamUrl =  ();
  upstreamUrl..(, mobileNumber);

   upstream =  (upstreamUrl.(), {
    : ,
    : {
      : ,
      : ,
    },
  });

  
   (upstream. ===  || upstream. === ) {
     errText =  upstream.();
      (errText, {
      : upstream.,
      : { :  },
    });
  }

   (!upstream.) {
      (
      .({ :  }),
      { : , : { :  } }
    );
  }

   data =  upstream.();
    (.(data), {
    : ,
    : { :  },
  });
});

前端调用（Web / MiniProgram 通用）

推荐方式（supabase client 可用时）：

/**
 * 通过 Edge Function 查询手机号归属地。
 * @param mobileNumber - 手机号，例如：13800138000
 * @returns 包含 area、originalIsp、isVirtuallyIsp 的对象
 */
async function fetchMobileLocation(mobileNumber: string) {
  const { data, error } = await supabase.functions.invoke("phone-location-lookup", {
    body: { mobile_number: mobileNumber },
  });
  if (error) throw error;
  if (data.code !== 200) throw new Error(`API 错误 ${data.code}：${data.msg}`);
  return data.data;
}

备用方式（无法使用 supabase client 时）：

/**
 * 通过原生 fetch 调用 Edge Function 查询手机号归属地。
 * @param mobileNumber - 手机号，例如：13800138000
 * @returns 包含 area、originalIsp、isVirtuallyIsp 的对象
 */
async function fetchMobileLocation(mobileNumber: string) {
  const res = await fetch(
    `${import.meta.env.VITE_SUPABASE_URL}/functions/v1/phone-location-lookup`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ mobile_number: mobileNumber }),
    }
  );

  if (res.status === 429) {
    const err = await res.json();
    throw new Error(`配额已用尽：${err.message ?? res.statusText}`);
  }
  if (res.status === 402) {
    const err = await res.json();
    throw new Error(`余额不足：${err.message ?? res.statusText}`);
  }
  if (!res.ok) throw  ();

   json =  res.();
   (json. !== )   ();
   json.;
}

参数说明

请求参数

参数名	类型	必填	说明
mobile_number	string	是	手机号，例如：13800138000。通过 URL Query 参数传递，不在请求体中

返回字段说明

成功响应（code: 200）：

字段路径	类型	说明
code	number	状态码，200 表示成功
taskNo	string	任务编号
data.area	string	手机号归属地（省份-城市），例如：江苏-南通
data.originalIsp	string	原运营商，例如：电信 / 移动 / 联通
data.isVirtuallyIsp	number	是否虚拟运营商：0 = 否，1 = 是

失败响应：

字段路径	类型	说明
code	number	错误码，见下表
msg	string	错误描述

错误码说明：

code	说明
400	参数错误（如手机号格式不正确）
501	官方数据源维护，请稍候再试
999	其他错误，以实际返回为准

注意事项

• 密钥安全：INTEGRATIONS_API_KEY 仅可在 Edge Function 服务端读取，严禁暴露到前端。
• 参数传递方式：mobile_number 必须通过 URL Query 参数传递，不在请求体中，请勿放入 POST body。
• 错误处理：务必处理 429（配额超限）和 402（余额不足），以及业务错误码 400 / 501 / 999。
• 计费：每次调用折扣价 ¥0.02（原价 ¥0.10），请避免不必要的重复调用。
• 数据时效：接口直连三大运营商实时查询，非缓存数据，可用于携号转网状态识别。
• Plugin ID：693a129f-b564-47d3-8d45-a080bab70148
• API ID：api-ELbWz8OmB58Y