{"id":19210378,"url":"https://github.com/seniverse/seniverse-api","last_synced_at":"2025-05-12T19:23:50.714Z","repository":{"id":78454334,"uuid":"218679735","full_name":"seniverse/seniverse-api","owner":"seniverse","description":"心知天气 API Node.js（支持 Typescript）SDK","archived":false,"fork":false,"pushed_at":"2019-11-02T04:47:16.000Z","size":54,"stargazers_count":18,"open_issues_count":2,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-12T19:23:45.493Z","etag":null,"topics":["api","sdk","seniverse","typescript","weather"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seniverse.png","metadata":{"files":{"readme":"README-EN.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-10-31T03:47:33.000Z","updated_at":"2025-05-09T01:56:37.000Z","dependencies_parsed_at":"2023-03-13T20:13:36.436Z","dependency_job_id":null,"html_url":"https://github.com/seniverse/seniverse-api","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":"0.11111111111111116","last_synced_commit":"360f86f991ced2fa2ba17d9a6ca6be642b9c95c3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seniverse%2Fseniverse-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seniverse%2Fseniverse-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seniverse%2Fseniverse-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seniverse%2Fseniverse-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seniverse","download_url":"https://codeload.github.com/seniverse/seniverse-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253806504,"owners_count":21967180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","sdk","seniverse","typescript","weather"],"created_at":"2024-11-09T13:35:56.175Z","updated_at":"2025-05-12T19:23:50.691Z","avatar_url":"https://github.com/seniverse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Seniverse-API\n\n\u003e 心知天气 API Node.js（Support Typescript）SDK [【语言--中文】](./README.md)\n\n[![npm version](https://badge.fury.io/js/seniverse-api.svg)](https://badge.fury.io/js/seniverse-api)  [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com) [![seniverse-api](http://img.shields.io/npm/dm/seniverse-api.svg)](https://www.npmjs.com/package/seniverse-api) ![GitHub](https://img.shields.io/github/license/seniverse/seniverse-api)\n\n[![NPM](https://nodei.co/npm/seniverse-api.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/seniverse-api)\n\n\n## Usage\n\n```bash\n$ npm i seniverse-api --save\n```\n\n```javascript\nimport { SeniverseV3 } from 'seniverse-api'\n\nconst seniverseV3 = new SeniverseV3({\n  encryption: {\n    uid: '', // Public Key\n    key: '', // Private Key\n    ttl: 10000, // Signature expiration times\n    enabled: false // Enable Signature verification or not\n  },\n  query: {\n    unit: 'c', // Unit\n    language: '', // Return language\n    timeouts: [3000, 3000] // [retry times,overtime times]\n  },\n  // memory cache\n  cache: {\n    ttl: 100, // Cache time，unit is second，It can set as 'auto'\n    max: 1000, // Numbers of cache data\n    enabled: true // Enable open cache or not\n  },\n  returnRaw: false // Return directly the API's raw data or not\n})\n\nawait seniverseV3.weather.daily.data({ days: 2, start: -1, location: 'beijing' })\nawait seniverseV3.air.hourlyHistory.data({ scope: 'city', location: 'beijing' })\n\n// Called via API URL\nawait seniverseV3.request(\n  '/weather/daily',\n  { days: 2, start: -1, location: 'beijing' }\n)\n\n// Generate jsonp call the link\nseniverseV3.jsonp(\n  '/weather/daily',\n  {\n    encryption: {\n      ttl: 1000,\n      uid: '',\n      key: '',\n    },\n    query: {\n      callback: 'weatherDaily',\n      location: 'beijing'\n    }\n  }\n)\n```\n\n## API\n\n### Create instance\n\n```javascript\nimport { SeniverseV3 } from 'seniverse-api'\n\nconst seniverseV3 = new SeniverseV3({\n  // Memory cache\n  cache: {\n    ttl: 100, // Cache time, unit is second\n    max: 1000, // Numbers of cache data\n    enabled: true // Enable open cache or not\n  },\n  encryption: {\n    uid: '', // public key\n    key: '', // private key\n    ttl: 100, // Signature expiration times, unit is second\n    enabled: true // Enable Signature verification or not\n  },\n  query: {\n    language: 'zh-Hans', // Return language, can change in calling\n    location: 'beijing', // Position, can change in calling\n    unit: 'c', // Unit, can change in calling\n    timeouts: [3000, 5000, 7000] // Numbers of retry and overtime times, unit is millisecond\n  },\n  returnRaw: false // Return directly the API's raw data or not\n})\n```\n\n配置说明：\n\n- `encryption`: API Encryption/verification configuration\n  - `uid`: string, public key, doc: https://docs.seniverse.com/api/start/key.html\n  - `key`: string, Private key, doc: https://docs.seniverse.com/api/start/key.html\n  - `ttl`: number, Encryption expiration times, unit is second, doc：https://docs.seniverse.com/api/start/validation.html\n  - `enabled`: boolean, Encryption or not，default is `true`\n- `cache`: Memory cache for request result\n  - `ttl`: number | string, Cache times，unit is second；or set as `auto`, Different cache times will be set according to different APIs（According to API update frequency）\n  - `max`: number, Data buffer. Overflow will overwrite old cache.\n  - `enabled`: boolean, Open cache or not. If the timeliness of the data is very high, it is not recommended to enable the cache. default is `false`\n- `query`: Request parameter\n  - `timeouts`: number[], Numbers of retry and overtime times, unit is millisecond. default is `[3000, 5000, 7000]`\n  - `language`: string, Return language, can changed by passed parameters in calling.doc：https://docs.seniverse.com/api/start/language.html default is `zh-Hans`\n  - `location`: string, Request position, can changed by passed parameters in calling.doc：https://docs.seniverse.com/api/start/common.html\n  - `unit`: string, Request unit，can changed by passed parameters in calling.doc：https://docs.seniverse.com/api/start/common.html default is `c`\n- `returnRaw`: boolean, Return directly the API's raw data or not. default is`false`\n\n### API Call\n\n#### Data calling method One\n\nFirst know the 心知天气API's URL，doc：https://docs.seniverse.com/\n\nWhen getting API data through the SDK, you need to call it based on the specific URL of the API, \nfor example:\n\n```javascript\nimport { SeniverseV3 } from 'seniverse-api'\n\nconst seniverseV3 = new SeniverseV3({ /* your config */ })\n\n// to real wheather API: https://api.seniverse.com/v3/weather/now.json\nawait seniverseV3.weather.now.data({\n  location: 'beijing',\n  language: 'zh-Hans',\n  unit: 'c'\n})\n\n// to weather for past 24 hours API：https://api.seniverse.com/v3/air/hourly_history.json\nawait seniverseV3.air.hourlyHistory.data({\n  location: 'beijing',\n  language: 'zh-Hans',\n  scope: 'city'\n})\n\n// For the lunar calendar API：https://api.seniverse.com/v3/life/chinese_calendar.json\nawait seniverseV3.life.chineseCalendar.data({\n  days: 2,\n  start: 0\n})\n```\n\nThat is, the API call rule is that the way the chain is called will be determined by the API URL. \nIf the URL contains an underscore `_`, it should be converted to a camel style:\n\n```\n/v3/weather/now.json =\u003e weather.now\n/v3/air/hourly_history.json =\u003e air.hourlyHistory\n/v3/life/chinese_calendar.json =\u003e life.chineseCalendar\n```\n\n#### Data calling method Two\n\nData calls are made through the route of the known weather API, which is more in line with the old user's usage habits.\n\n```javascript\nimport { SeniverseV3 } from 'seniverse-api'\n\nconst seniverseV3 = new SeniverseV3({ /* your config */ })\n\n// 调用 https://api.seniverse.com/v3/weather/daily.json\nawait seniverseV3.request(\n  '/weather/daily',\n  { days: 2, start: -1, location: 'beijing' }\n)\n\n// 调用 https://api.seniverse.com/v3/air/hourly_history.json\nawait seniverseV3.request(\n  '/air/hourly_history',\n  { scope: 'city', location: 'beijing' }\n)\n```\n\n#### Generate JSONP link\n\nUse JSONP method call：[description doc](https://docs.seniverse.com/api/start/jsonp.html)\n\n```javascript\nimport { SeniverseV3 } from 'seniverse-api'\n\nconst seniverseV3 = new SeniverseV3({ /* your config */ })\n\n// Generate JSONP link call https://api.seniverse.com/v3/weather/daily.json\nconst url = seniverseV3.jsonp(\n  '/weather/daily',\n  {\n    encryption: {\n      ttl: 1000, // Encryption expiration time, if configured during initialization, you can leave it blank\n      uid: '', // The public key, if configured during initialization, can be leave blank\n      key: '', // The private key, if configured during initialization, can be leave blank\n    },\n    query: {\n      callback: 'weatherDaily', // Callback function name\n      location: 'beijing' // Request parameter\n    }\n  }\n)\n\nseniverseV3.jsonp(\n  '/air/hourly',\n  {\n    // If ttl, uid, key are passed at initialization, the encryption field can be leave blank\n    query: {\n      callback: 'airHourly', // Callback function name\n      location: 'beijing' // Request parameter\n    }\n  }\n)\n```\n\n### Data return\n\nDetermine whether to return the original data by setting `returnRaw` when initializing `SeniverseV3`.(that is the same data as in the API document)\n\n1. If `returnRaw: false`, all interfaces return data as an array. Compare with [Raw API doc](https://docs.seniverse.com/), The returned result has been extracted from the `results` field, and the specific data is encapsulated into the `data` (array) field, eliminating the problem that the original API returns the result format is not uniform.\n2. If `returnRaw: true`, the returned result will not be processed, consistent with the results shown in the API documentation.\n\n## Demo\n\n[Use Demo](./src/scripts/demo.ts)\n\n## License\n\n[MIT License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseniverse%2Fseniverse-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseniverse%2Fseniverse-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseniverse%2Fseniverse-api/lists"}