NAV Navbar
Logo
python java php node

1 / 简介

BasaltMatrix 开放 API 采用 REST 风格设计。所有接口请求都是面向资源的。使用标准响应代码来表示请求结果的正确或错误。所有的 API 请求都会以规范友好的 JSON 对象格式返回（包括错误信息），每个response都会包含meta信息（请求本身的状态数据）和data信息（请求返回的响应数据）

测试环境API Root地址：https://testapi.basaltmatrix.com

2 / 认证

2.1 / 签名认证

所有的请求都要在HTTP头部加上以下这两个参数：

签名的生成规则如下：

  1. 将每个表单参数UTF-8编码，并用URL编码特殊符号。
  2. 将参数根据 key 按字典序排序后拼接成 key=value&key1=value1 形式的字符串。
  3. 将agent-key拼接到字符串后面。
  4. 用sha256哈希最终的结果得到签名signature。

agent-no和agent-key参数在接口开通后会由BasaltMatrix统一分配。

2.2 / 版本选择

所有接口默认使用最新版本，不需要指定版本号，部分接口会保留多个版本，如需指定版本请在头部传入version参数：

不同版本的接口差别请查看接口文档详情。

3 / 错误处理

Status Code 说明
400 Bad Request – 请求被拒绝
401 Unauthorized – API agent_no 或者 agent_key不正确
403 Forbidden – 无权访问
404 Not Found – 接口不存在
500 Internal Server Error – 内部服务出错，请稍后重试
503 Service Unavailable – 服务不可用，请稍后重试

4 / API 接口

4.1 / 个人证件真伪识别

GET /individual/doc/certification

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def certification():
    url = '{0}/individual/doc/certification'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'doc_no': '6223XXXXXXX82296',
        'name': 'XXX',
        'doc_type': 'CHN_ID'
    }
    result = requests.get(url, data)
    return result.content

Response

{
  "data": {
    "error_code": 0,
    "reason": "\u6210\u529f ",
    "result": {
      "idcard": "6223XXXXXXX82296",
      "realname": "XXX",
      "res": 1
    }
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
doc_no 证件号码 是
name 姓名 是
doc_type 证件类型 是 中国二代身份证：CHN_ID

4.2 / 个人证件图像识别

POST /individual/doc/ocr

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def ocr(img_file):
    url = '{0}/individual/doc/ocr'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'doc_type': 'CHN_ID'
    }
    files = {
        'img': img_file
    }
    result = requests.get(url, data, files=files)
    return result.content

Response

{
    "data": {
        "birthday": "1976-03-20",
        "dwelling_place": "湖南省邵阳******",
        "ethnicity": "汉",
        "id_no": "430523********",
        "name": "蒋**",
        "sex": "男"
    },
    "meta": {
        "message": "请求成功",
        "status_code": 200,
        "success": true
    }
}
参数 含义 是否必填 说明
img 证件照片 是 文件流
doc_type 证件类型 是 中国二代身份证：CHN_ID；护照：PASSPORT

4.3 / 个人全球监控名单查询

GET /screening/individual/v2

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def individual_screening():
    url = '{0}/screening/individual'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'name': '刘凯',
        'gender': 'Male',
        'max_count': '1',
        'min_score': '100'
    }
    result = requests.get(url, data)
    return result.content

Response version 1.0

{
  "data": [
    {
      "additional_info": [
        {
          "comments": null,
          "id": 0,
          "type": "DOB",
          "value": "1958-10-XX"
        },
        {
          "comments": "http://www.circ.gov.cn/web/site0/tab3050/info4049335.htm",
          "id": 0,
          "type": "Other",
          "value": "Sources of Record Information"
        }
      ],
      "conflicts": {
        "address_conflict": false,
        "citizenship_conflict": false,
        "country_conflict": false,
        "dob_conflict": false,
        "entity_type_conflict": false,
        "gender_conflict": false,
        "id_conflict": false,
        "phone_conflict": false
      },
      "gender": null,
      "information": "Source: China,CN-Insurance Regulatory Commission || Offense: Fined for violating the Insurance Law - November 02, 2016 || Category: Enforcement | Subcategory: Disciplined || Associations: | Affiliated Company (Enforcement:Disciplined): PICC Life Insurance Company Limited (Ganzhou Branch), 5632826 || Last updated: 2016-11-08 || Profile Notes: According  to circ.gov.cn; November 08, 2016: Liu Kai, General Manager of PICC Life Insurance Company Limited (Ganzhou Branch), was fined CNY 35,000 for violating the Insurance Law and Measures for the Administration of the Disclosure of Information on New-Type Personal Insurance Products by the Jiangxi Bureau of the China Insurance Regulatory Commission on November 02, 2016. In line with the investigation, in 2015, firstly, PICC Life Insurance Company Limited (Ganzhou Branch)'s expense reimbursement invoice records were inconsistent with actual occurrences. Secondly, the branch also gave the insured or the beneficiary benefits other than the ones provided for in the insurance contracts. Finally, the branch also sought  illegitimate benefits for others in the process of insurance business operation. The acts mentioned above of the branch violated the Article 86, 116 of the Insurance Law and the Article 10 of the Administration of the Disclosure of Information on New-Type Personal Insurance Products. Liu was directly responsible for the above violations of the branch.",
      "name": "\u5218\u51ef",
      "name_detail": {
        "first": "Kai",
        "full": "Kai Liu",
        "generation": null,
        "last": "Liu",
        "middle": null,
        "title": null
      },
      "reason": "Enforcement:Disciplined",
      "score": 100
    }
  ],
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}

Response version 2.0

{
  "data": [
    {
      "alias": "刘凯",
      "category": "Enforcement",
      "country": "CHN",
      "dob": "1994-*-*",
      "doc_no": "{"national_id": "6123211994********"}",
      "effective_date": "",
      "entity_type": "Individual",
      "gender": "Male",
      "hit_reason": "Fraud",
      "id": 2946570,
      "name": "Liu, Kai",
      "photo": "",
      "pob": "Hanzhong, Shaanxi, China",
      "ranking": 113,
      "remarks": null,
      "risk_level": 8,
      "score": 97,
      "source": "http://www.ajxxgk.jcy.cn/html/20170109/2/4221573.html;http://www.ajxxgk.jcy.gov.cn/html/20170109/2/4221573.html",
      "sub_category": "Fraud"
    }
  ],
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}

version 2.0 该版本更新了评分算法，针对国内的信息更为全面，请求参数和返回结果格式略有不通。

参数 解释 是否必填 说明
name 姓名 是
dob 出生日期 否 格式必须为 yyyy-mm-dd(1980-02-05)形式
gender 性别 否 Male/Female
max_count 最大匹配数量 否 默认为20，即按分值排序取前20条
min_score 评分 否 0-100，评分值高于该值的才会返回，默认为60

4.4 / 企业/机构信息查询

GET /enterprise

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def query_enterprise():
    url = '{0}/enterprise'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'name': '',
        'enterprise_no': '07209813',
        'country_code': 'GBR'
    }
    result = requests.get(url, data)
    return result.content

Response

{
  "data": {
    "base_info": {
      "address": {
        "address_line_1": "Floor, Tea Building",
        "address_line_2": "56 Shoreditch High Street",
        "country": "England",
        "locality": "London",
        "postal_code": "E1 6JJ",
        "premises": "6th"
      },
      "credit_no": "07209813",
      "econ_kind": "ltd",
      "end_date": "",
      "name": "TRANSFERWISE LTD",
      "oper_name": "",
      "province": "",
      "regist_capi": "",
      "scope": "",
      "start_date": "2010-03-31",
      "status": "active",
      "term_end": "",
      "term_start": ""
    },
    "expand_info": {
      "address_snippet": "6th Floor, Tea Building, 56 Shoreditch High Street, London, England, E1 6JJ",
      "description": "07209813 - Incorporated on 31 March 2010",
      "description_identifier": [
        "incorporated-on"
      ],
      "links": {
        "self": "/company/07209813"
      },
      "matches": null,
      "snippet": null
    }
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
name 企业名称 否 必须填写企业全称
enterprise_no 企业证件号 否 name 或者 enterprise_no 必须有一个不为空
country_code 国家编码 是 开放情况请见下表
国家/地区名称 国家/地区三位编码 说明
中国 CHN 只可以通过 name查询
中国香港 HKG 通过name或者enterprise_no查询
澳大利亚 AUS 只可以通过 enterprise_no查询
加拿大 CAN 只可以通过 enterprise_no查询
美国 USA 只可以通过 enterprise_no查询
英国 GBR 只可以通过 name查询
新西兰 NZL 只可以通过 enterprise_no查询
泰国 THA 只可以通过 name查询

4.5 / 企业/机构全球监控名单查询

GET /screening/org/v2

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def org_screening():
    url = '{0}/screening/org'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'name': 'Money Data Limited',
        'min_score': '85',
        'max_count': '1'
    }
    result = requests.get(url, data)
    return result.content

Response version 1.0

{
  "data": [
    {
      "additional_info": [
        {
          "comments": "http://web.archive.org/web/20091228052532/http://www.sec.gov.ng/index.php/enfactions/action/view/pageID/1 | http://www.sec.gov.ng/index.php/enfactions/action/view/pageID/1/#",
          "id": 0,
          "type": "Other",
          "value": "Sources of Record Information"
        }
      ],
      "address": [
        {
          "city": null,
          "comments": null,
          "country": "Nigeria",
          "id": 0,
          "postal_code": null,
          "state_province_district": null,
          "street_1": null,
          "street_2": null,
          "type": "Unknown"
        }
      ],
      "conflicts": {
        "address_conflict": false,
        "citizenship_conflict": false,
        "country_conflict": false,
        "dob_conflict": false,
        "entity_type_conflict": false,
        "gender_conflict": false,
        "id_conflict": false,
        "phone_conflict": false
      },
      "information": "Source: Nigeria,NG-Securities and Exchange Commission of Nigeria (SEC) || Offense: Sanctioned by the Securities and Exchange Commission of Nigeria for failure to file Quarterly returns \u2013 January 01, 2009 || Category: Enforcement | Subcategory: Disciplined || Last updated: 2015-09-03 || Profile Notes: According to the Securities and Exchange Commission Nigeria; January 01, 2009: Data Pro Limited, failure to file Quarterly returns.",
      "name": "Data Pro Limited",
      "reason": "Enforcement:Disciplined",
      "score": 85
    }
  ],
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}

Response version 2.0

{
  "data": [
    {
      "additional_info": [
        {
          "comments": "http://web.archive.org/web/20091228052532/http://www.sec.gov.ng/index.php/enfactions/action/view/pageID/1 | http://www.sec.gov.ng/index.php/enfactions/action/view/pageID/1/#",
          "id": 0,
          "type": "Other",
          "value": "Sources of Record Information"
        }
      ],
      "address": [
        {
          "city": null,
          "comments": null,
          "country": "Nigeria",
          "id": 0,
          "postal_code": null,
          "state_province_district": null,
          "street_1": null,
          "street_2": null,
          "type": "Unknown"
        }
      ],
      "conflicts": {
        "address_conflict": false,
        "citizenship_conflict": false,
        "country_conflict": false,
        "dob_conflict": false,
        "entity_type_conflict": false,
        "gender_conflict": false,
        "id_conflict": false,
        "phone_conflict": false
      },
      "information": "Source: Nigeria,NG-Securities and Exchange Commission of Nigeria (SEC) || Offense: Sanctioned by the Securities and Exchange Commission of Nigeria for failure to file Quarterly returns \u2013 January 01, 2009 || Category: Enforcement | Subcategory: Disciplined || Last updated: 2015-09-03 || Profile Notes: According to the Securities and Exchange Commission Nigeria; January 01, 2009: Data Pro Limited, failure to file Quarterly returns.",
      "name": "Data Pro Limited",
      "reason": "Enforcement:Disciplined",
      "score": 85
    }
  ],
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
name 企业名称 是 必须填写企业全称
min_score 最低分值 否 0-100，默认为40
max_count 返回数量 否 默认为20，即按分值排序取前20条

4.6 / 银行卡bin查询

GET /card_bin

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def card_bin():
    url = '{0}/card_bin'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'card_bin': '442867'
    }
    result = requests.get(url, data)
    return result.content

Response


{
  "data": {
    "bank_name": "JPMORGAN CHASE BANK",
    "bin": "442867",
    "card_type": "CREDIT",
    "code": "CHAS",
    "country_code": "USA",
    "issuer": "VISA",
    "zh_name": "摩根大通银行"
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
card_bin 银行卡卡bin 是 银行卡号前6位

目前支持全球40万+的银行卡卡bin识别

4.7 / IP信息查询

GET /lbs/ip_info

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def ip():
    url = '{0}/lbs/ip_info'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'ip': '111.198.29.21'
    }
    result = requests.get(url, data)
    return result.content

Response

{
  "data": {
    "city": "Beijing",
    "country": "CN",
    "hostname": "No Hostname",
    "ip": "111.198.29.21",
    "loc": "39.9289,116.3883",
    "org": "AS4808 China Unicom Beijing Province Network",
    "region": "Beijing"
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
ip IP地址 是

4.8 / 地理位置信息查询

GET /lbs/location_info

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def location():
    url = '{0}/lbs/location_info'.format(HOST)
    data = {
        'agent_key': agent_key,
        'agent_no': agent_no,
        'location': '22.3169,114.1664'
    }
    result = requests.get(url, data)
    return result.content

Response

{
  "data": {
    "ad_info": {
      "adcode": "810109",
      "city": "香港特别行政区",
      "district": "油尖旺区",
      "location": {
        "lat": 22.3169,
        "lng": 114.166397
      },
      "name": "中国,,香港特别行政区,油尖旺区",
      "nation": "中国",
      "province": ""
    },
    "address": "香港特别行政区油尖旺区博文街",
    "address_component": {
      "city": "香港特别行政区",
      "district": "油尖旺区",
      "nation": "中国",
      "province": "",
      "street": "博文街",
      "street_number": ""
    },
    "address_reference": {
      "business_area": {
        "_dir_desc": "内",
        "_distance": 0,
        "location": {
          "lat": 22.3169,
          "lng": 114.166397
        },
        "title": "大角咀"
      },
      "crossroad": {
        "_dir_desc": "西",
        "_distance": 51.6,
        "location": {
          "lat": 22.31679,
          "lng": 114.166939
        },
        "title": "大角咀道/博文街(路口)"
      },
      "famous_area": {
        "_dir_desc": "内",
        "_distance": 0,
        "location": {
          "lat": 22.3169,
          "lng": 114.166397
        },
        "title": "大角咀"
      },
      "landmark_l1": {
        "_dir_desc": "西南",
        "_distance": 150.1,
        "location": {
          "lat": 22.318319,
          "lng": 114.167099
        },
        "title": "九龙珀丽酒店"
      },
      "landmark_l2": {
        "_dir_desc": "西",
        "_distance": 88.5,
        "location": {
          "lat": 22.316879,
          "lng": 114.167412
        },
        "title": "新九龙广场"
      },
      "street": {
        "_dir_desc": "北",
        "_distance": 7.5,
        "location": {
          "lat": 22.316784,
          "lng": 114.166389
        },
        "title": "博文街"
      },
      "street_number": {
        "_dir_desc": "北",
        "_distance": 7.5,
        "location": {
          "lat": 22.316784,
          "lng": 114.166389
        },
        "title": ""
      }
    },
    "formatted_addresses": {
      "recommend": "油尖旺区大角咀博文街新九龙广场西100米",
      "rough": "油尖旺区大角咀博文街新九龙广场西100米"
    },
    "location": {
      "lat": 22.3169,
      "lng": 114.1664
    }
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
location 经纬度 是 例如 22.3169,114.1664

4.9 / 中国大陆身份证黑名单查询

POST /screening/chn_id

通过中国大陆的身份证号来查询是否命中黑名单，并返回命中结果详情。

Request

# -*- coding: utf-8 -*-
import requests
from config import HOST, agent_key, agent_no

def chn_id_screening():
    url = HOST + '/screening/chn_id'
    data = {
        'name': '张某',
        'chn_id_hash': 'ea996a4c9e962b25d7733790e69b4a87'
    }
    result = requests.post(url, data, headers=gen_header(data))
    return result.content

Response


{
  "data": [
    {
      "alias": "chenyijuan",
      "category": "Wanted",
      "country": "CHN",
      "detail_info": {
        "filing_unit": "湖南省益阳市检察院",
        "fled_country": "英国",
        "fled_time": "2013.4",
        "gender": "女",
        "id_card": "42011119700703556X",
        "id_hash": "ea996a4c9e962b25d7733790e69b4a87",
        "name": "陈祎娟",
        "no": "0567a241190a6a079bfcffc8ab59d6e9",
        "passport": "G29937849",
        "photo": "http://www.ccdi.gov.cn/images/wtry_15.png",
        "position": "中国移动通信集团终端公司湖南分公司综合部员工",
        "source": "http://www.ccdi.gov.cn/xwtt/201504/t20150422_55183.html",
        "spider": "manual",
        "status": 1,
        "wanted_level": "HT-wanted",
        "wanted_no": "A-7810/12-2013",
        "wanted_reason": "洗钱",
        "wanted_time": "2013.12.3"
      },
      "dob": "",
      "doc_no": "{"id_card": "42011119700703556X", "passport": "G29937849"}",
      "effective_date": "2013.12.3",
      "entity_type": "Individual",
      "gender": "Female",
      "hit_reason": "被列入通缉名单",
      "id": 6250512,
      "name": "陈祎娟",
      "photo": "http://www.ccdi.gov.cn/images/wtry_15.png",
      "pob": null,
      "remarks": "洗钱",
      "risk_level": 1,
      "source": "http://www.ccdi.gov.cn/xwtt/201504/t20150422_55183.html",
      "sub_category": "HT-wanted"
    }
  ],
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 含义 是否必填 说明
name 姓名 否 待查询人姓名
chn_id_hash 身份证号哈希 是 中国大陆身份证的md5哈希值

注意：哈希计算结果小写，参与计算的身份证号中间勿添加其他特殊符号或空格，身份证号末尾X使用大写。

5 / 附录

5.1 / 国家/地区编码

名称 三位编码
中国 CHN
中国香港 HKG
澳大利亚 AUS
加拿大 CAN
美国 USA
英国 GBR
日本 JPN
新西兰 NZL
泰国 THA

6 / 帮助

python java php node