npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

seniverse-api

v0.1.2

Published

Api sdk for seniverse

Downloads

8

Readme

Seniverse-API

心知天气 API Node.js(支持 Typescript)SDK

npm version js-standard-style seniverse-api Hex.pm

NPM

Usage

$ npm i seniverse-api --save
import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({
  encryption: {
    uid: '', // 公钥
    key: '', // 私钥
    ttl: 10000, // 签名失效时间
    enabled: false // 是否进行签名验证
  },
  query: {
    unit: 'c', // 单位
    language: '', // 结果返回语言
    timeouts: [3000, 3000] // 重试次数和超时时间
  },
  // 内存缓存
  cache: {
    ttl: 100, // 缓存时间,单位为秒,可以为 'auto'
    max: 1000, // 缓存数据条数
    enabled: true // 是否开启缓存
  },
  returnRaw: false // 是否直接返回 API 原始数据
})

await seniverseV3.weather.daily.data({ days: 2, start: -1, location: 'beijing' })
await seniverseV3.air.hourlyHistory.data({ scope: 'city', location: 'beijing' })

// 通过 API URL 调用
await seniverseV3.request(
  '/weather/daily',
  { days: 2, start: -1, location: 'beijing' }
)

// 生成 jsonp 调用链接
seniverseV3.jsonp(
  '/weather/daily',
  {
    encryption: {
      ttl: 1000,
      uid: '',
      key: '',
    },
    query: {
      callback: 'weatherDaily',
      location: 'beijing'
    }
  }
)

API

创建实例

import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({
  // 内存缓存
  cache: {
    ttl: 100, // 缓存时间,单位为秒
    max: 1000, // 缓存数据条数
    enabled: true // 是否开启缓存
  },
  encryption: {
    uid: '', // 公钥
    key: '', // 私钥
    ttl: 100, // 签名失效时间,单位为秒
    enabled: true // 是否进行签名验证
  },
  query: {
    language: 'zh-Hans', // 结果返回语言,可在调用时修改
    location: 'beijing', // 地点,可在调用时修改
    unit: 'c', // 单位,可在调用时修改
    timeouts: [3000, 5000, 7000] // 调用 API 时重试次数以及 timeout 时间,单位为毫秒
  },
  returnRaw: false // 是否直接返回 API 原始数据
})

配置说明:

  • encryption: API 加密/验证配置
    • uid: string, 公钥,文档 https://docs.seniverse.com/api/start/key.html
    • key: string, 私钥,文档 https://docs.seniverse.com/api/start/key.html
    • ttl: number, 加密过期时间,单位为秒,文档:https://docs.seniverse.com/api/start/validation.html
    • enabled: boolean, 是否开启加密,默认为true
  • cache: 对请求结果进行内存缓存
    • ttl: number | string, 缓存时间,单位为秒;或设置为auto,将会根据不同 API 设定不同缓存时间(根据 API 更新频率)
    • max: number, 数据缓存量。超出将会覆盖旧缓存
    • enabled: boolean, 是否开启缓存。如果对数据时效性要求很高,则不建议开启缓存。默认为false
  • query: 请求参数
    • timeouts: number[], 调用 API 时重试次数以及 timeout 时间,单位为毫秒。默认为[3000, 5000, 7000]
    • language: string, 结果返回语言,具体调用时可通过传入的参数更改。文档:https://docs.seniverse.com/api/start/language.html 默认为zh-Hans
    • location: string, 请求地点,具体调用时可通过传入的参数更改。文档:https://docs.seniverse.com/api/start/common.html
    • unit: string, 请求单位,具体调用时可通过传入的参数更改。文档:https://docs.seniverse.com/api/start/common.html 默认为c
  • returnRaw: boolean, 是否直接返回 API 原始数据。默认为false

API 调用

数据调用方式一

首先需要了解心知天气 API 的 URL,可见文档:https://docs.seniverse.com/

通过 SDK 获取 API 数据时,需要根据该 API 的具体 URL 来进行调用,例如:

import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({ /* your config */ })

// 对于实况天气 API: https://api.seniverse.com/v3/weather/now.json
await seniverseV3.weather.now.data({
  location: 'beijing',
  language: 'zh-Hans',
  unit: 'c'
})

// 对于过去 24 小时历史空气 API:https://api.seniverse.com/v3/air/hourly_history.json
await seniverseV3.air.hourlyHistory.data({
  location: 'beijing',
  language: 'zh-Hans',
  scope: 'city'
})

// 对于农历节气 API:https://api.seniverse.com/v3/life/chinese_calendar.json
await seniverseV3.life.chineseCalendar.data({
  days: 2,
  start: 0
})

即,API 调用规律为,链式调用的方式将由 API URL 决定。如果 URL 内含有下划线_,则应转变为驼峰式写法:

/v3/weather/now.json => weather.now
/v3/air/hourly_history.json => air.hourlyHistory
/v3/life/chinese_calendar.json => life.chineseCalendar

数据调用方式二

通过传入心知天气 API 的路由进行数据调用,更符合老用户的使用习惯

import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({ /* your config */ })

// 调用 https://api.seniverse.com/v3/weather/daily.json
await seniverseV3.request(
  '/weather/daily',
  { days: 2, start: -1, location: 'beijing' }
)

// 调用 https://api.seniverse.com/v3/air/hourly_history.json
await seniverseV3.request(
  '/air/hourly_history',
  { scope: 'city', location: 'beijing' }
)

生成 JSONP 链接

使用 JSONP 方式调用:说明文档

import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({ /* your config */ })

// 生成 JSONP 链接调用 https://api.seniverse.com/v3/weather/daily.json
const url = seniverseV3.jsonp(
  '/weather/daily',
  {
    encryption: {
      ttl: 1000, // 加密过期时间,如在初始化中已经配置,则可不填
      uid: '', // 公钥,如在初始化中已经配置,则可不填
      key: '', // 私钥,如在初始化中已经配置,则可不填
    },
    query: {
      callback: 'weatherDaily', // 回调函数名
      location: 'beijing' // 请求参数
    }
  }
)

seniverseV3.jsonp(
  '/air/hourly',
  {
    // 如果 ttl, uid, key 都已在初始化时传递,则 encryption 字段可不传
    query: {
      callback: 'airHourly', // 回调函数名
      location: 'beijing' // 请求参数
    }
  }
)

数据返回

  1. 如果没有设置returnRaw: true,则所有接口均以数组形式返回数据。相较于原始 API 文档,返回的结果已经从results字段中抽出,并将具体数据封装进data(数组)字段,消除了原有 API 返回结果格式不统一的问题
  2. 如果设置returnRaw: true,则返回结果将不做处理,和 API 文档展示的结果一致

Demo

使用样例

License

MIT License