Public API v1

راهنمای توسعه‌دهندگان

داده‌های پکت‌ها و تلمتری ماهواره به‌صورت عمومی در دسترس است. بدون نیاز به احراز هویت، با درخواست‌های GET می‌توانید آخرین پکت‌ها یا سری زمانی یک فیلد را دریافت کنید.

Base URL

https://gateway.spaceomid.com/iot/public/v1

محدودیت نرخ

هر IP حداکثر ۲۰ درخواست در دقیقه. در صورت عبور، پاسخ با کد 429 و هدر Retry-After بازگردانده می‌شود. لطفاً نتایج را کش کنید.

قالب پاسخ

همه پاسخ‌ها با کد HTTP 200 و قالب زیر بازگردانده می‌شوند؛ resultStatus=0 یعنی موفق.

Envelope

{
  "validationMessage": [{ "statusCode": 200, "message": "ok" }],
  "result": { "items": [ /* ... */ ], "total": 1234 },
  "resultStatus": 0
}

Endpoint ها

GET/telemetry/fields— فهرست فیلدهای تلمتری

فیلدهای عددی موجود در پکت‌های اخیر و فهرست ماهواره‌ها.

پارامتر	توضیح
`sample`	تعداد پکت‌های اخیر برای اسکن (پیش‌فرض 200، حداکثر 2000)

curl

curl "https://gateway.spaceomid.com/iot/public/v1/telemetry/fields?sample=200"

نمونه پاسخ

{
  "result": {
    "items": [
      { "key": "battery1_total_voltage", "count": 29, "sample": 23535.0 },
      { "key": "link1_temp3", "count": 38, "sample": 19.0 }
    ],
    "satellites": ["KOSAR 1.5 433"],
    "scanned": 300
  },
  "resultStatus": 0
}

GET/telemetry/series— سری زمانی یک فیلد

مقادیر یک فیلد تلمتری بر حسب زمان. می‌توانید بر اساس تعداد پکت (limit) یا بازه زمانی (from_t/to_t به میلی‌ثانیه) انتخاب کنید.

پارامتر	توضیح
`field`	کلید فیلد (اجباری) — مثلاً battery1_total_voltage
`limit`	تعداد پکت‌های اخیر (پیش‌فرض 1000، حداکثر 100000)
`from_t`	کران پایین زمان (epoch ms)
`to_t`	کران بالای زمان (epoch ms)
`satellite`	فیلتر اختیاری نام ماهواره

curl

curl "https://gateway.spaceomid.com/iot/public/v1/telemetry/series?field=battery1_total_voltage&limit=1000"

# or by time range (epoch milliseconds)
curl "https://gateway.spaceomid.com/iot/public/v1/telemetry/series?field=battery1_total_voltage&from_t=1790793600000"

نمونه پاسخ

{
  "validationMessage": [{ "statusCode": 200, "message": "Telemetry series fetched successfully" }],
  "result": {
    "field": "battery1_total_voltage",
    "points": [
      { "t": 1790794033000, "v": 22496.0 },
      { "t": 1790794091000, "v": 22389.0 }
    ],
    "count": 103,
    "sampled": false,
    "window": 1000,
    "from_t": 1790794033000,
    "to_t": 1791017033000
  },
  "resultStatus": 0
}

GET/packets— فهرست پکت‌ها

آخرین پکت‌های دریافتی (بدون داده تلمتری رمزگشایی‌شده).

پارامتر	توضیح
`limit`	تعداد در هر صفحه (پیش‌فرض 50، حداکثر 500)
`page`	شماره صفحه
`mode`	both \| telemetry \| message
`kind`	telemetry \| beacon \| iot_packet \| unknown
`satellite`	فیلتر اختیاری نام ماهواره

curl

curl "https://gateway.spaceomid.com/iot/public/v1/packets?limit=50&page=1&mode=telemetry"

GET/packets/{es_id}— یک پکت

یک پکت کامل (شامل تلمتری رمزگشایی‌شده) با شناسه Elasticsearch.

پارامتر	توضیح
`es_id`	شناسه پکت (مسیر)

پکت‌های IoT و بیکن

پکت‌های بیکن (S01000) و IoT (S01Pxx) می‌توانند هر نوع داده‌ای حمل کنند: متن ساده (مثل hello)، داده دودویی یا داده رمزشده. برای هر پکت، فیلد packet_type (کد نوع) و data بازگردانده می‌شود؛ دادهٔ خام بعد از هدر ۶ بایتی قرار دارد.

data.base64 — دادهٔ خام به‌صورت Base64
data.hex — همان داده به‌صورت Hex
data.text — متن UTF-8 (در صورت قابل‌چاپ بودن، وگرنه null)
data.length و data.is_text

curl (IoT packets)

curl "https://gateway.spaceomid.com/iot/public/v1/packets?limit=50&page=1&mode=message&kind=iot_packet"

نمونه پاسخ

{
  "result": {
    "items": [
      {
        "es_id": "OcnQ86ABw4ga0JVupLps",
        "kind": "iot_packet",
        "packet_type": "S01Pab",
        "message": "hello",
        "data": {
          "base64": "aGVsbG8=",
          "hex": "68656c6c6f",
          "text": "hello",
          "length": 5,
          "is_text": true
        }
      }
    ],
    "total": 1234
  },
  "resultStatus": 0
}

دموی تعاملی سری زمانی

این نمودار مستقیماً از همین API عمومی داده می‌گیرد:

نمودار داده تلمتری

یک فیلد و تعداد پکت‌های اخیر را انتخاب کنید

Spec و خطاها

مشخصات OpenAPI در آدرس زیر موجود است:

https://gateway.spaceomid.com/iot/public/v1/openapi.json

400 — پارامتر نامعتبر
404 — پکت یافت نشد
429 — عبور از حد مجاز
502 — خطای سرویس بالادستی

Public API v1

راهنمای توسعه‌دهندگان

Base URL

https://gateway.spaceomid.com/iot/public/v1

محدودیت نرخ

قالب پاسخ

همه پاسخ‌ها با کد HTTP 200 و قالب زیر بازگردانده می‌شوند؛ resultStatus=0 یعنی موفق.

Envelope

{
  "validationMessage": [{ "statusCode": 200, "message": "ok" }],
  "result": { "items": [ /* ... */ ], "total": 1234 },
  "resultStatus": 0
}

Endpoint ها

GET/telemetry/fields— فهرست فیلدهای تلمتری

فیلدهای عددی موجود در پکت‌های اخیر و فهرست ماهواره‌ها.

پارامتر	توضیح
`sample`	تعداد پکت‌های اخیر برای اسکن (پیش‌فرض 200، حداکثر 2000)

curl

curl "https://gateway.spaceomid.com/iot/public/v1/telemetry/fields?sample=200"

نمونه پاسخ

{
  "result": {
    "items": [
      { "key": "battery1_total_voltage", "count": 29, "sample": 23535.0 },
      { "key": "link1_temp3", "count": 38, "sample": 19.0 }
    ],
    "satellites": ["KOSAR 1.5 433"],
    "scanned": 300
  },
  "resultStatus": 0
}

GET/telemetry/series— سری زمانی یک فیلد

پارامتر	توضیح
`field`	کلید فیلد (اجباری) — مثلاً battery1_total_voltage
`limit`	تعداد پکت‌های اخیر (پیش‌فرض 1000، حداکثر 100000)
`from_t`	کران پایین زمان (epoch ms)
`to_t`	کران بالای زمان (epoch ms)
`satellite`	فیلتر اختیاری نام ماهواره

curl

curl "https://gateway.spaceomid.com/iot/public/v1/telemetry/series?field=battery1_total_voltage&limit=1000"

# or by time range (epoch milliseconds)
curl "https://gateway.spaceomid.com/iot/public/v1/telemetry/series?field=battery1_total_voltage&from_t=1790793600000"

نمونه پاسخ

{
  "validationMessage": [{ "statusCode": 200, "message": "Telemetry series fetched successfully" }],
  "result": {
    "field": "battery1_total_voltage",
    "points": [
      { "t": 1790794033000, "v": 22496.0 },
      { "t": 1790794091000, "v": 22389.0 }
    ],
    "count": 103,
    "sampled": false,
    "window": 1000,
    "from_t": 1790794033000,
    "to_t": 1791017033000
  },
  "resultStatus": 0
}

GET/packets— فهرست پکت‌ها

آخرین پکت‌های دریافتی (بدون داده تلمتری رمزگشایی‌شده).

پارامتر	توضیح
`limit`	تعداد در هر صفحه (پیش‌فرض 50، حداکثر 500)
`page`	شماره صفحه
`mode`	both \| telemetry \| message
`kind`	telemetry \| beacon \| iot_packet \| unknown
`satellite`	فیلتر اختیاری نام ماهواره

curl

curl "https://gateway.spaceomid.com/iot/public/v1/packets?limit=50&page=1&mode=telemetry"

GET/packets/{es_id}— یک پکت

یک پکت کامل (شامل تلمتری رمزگشایی‌شده) با شناسه Elasticsearch.

پارامتر	توضیح
`es_id`	شناسه پکت (مسیر)

پکت‌های IoT و بیکن

data.base64 — دادهٔ خام به‌صورت Base64
data.hex — همان داده به‌صورت Hex
data.text — متن UTF-8 (در صورت قابل‌چاپ بودن، وگرنه null)
data.length و data.is_text

curl (IoT packets)

curl "https://gateway.spaceomid.com/iot/public/v1/packets?limit=50&page=1&mode=message&kind=iot_packet"

نمونه پاسخ

{
  "result": {
    "items": [
      {
        "es_id": "OcnQ86ABw4ga0JVupLps",
        "kind": "iot_packet",
        "packet_type": "S01Pab",
        "message": "hello",
        "data": {
          "base64": "aGVsbG8=",
          "hex": "68656c6c6f",
          "text": "hello",
          "length": 5,
          "is_text": true
        }
      }
    ],
    "total": 1234
  },
  "resultStatus": 0
}

دموی تعاملی سری زمانی

این نمودار مستقیماً از همین API عمومی داده می‌گیرد:

نمودار داده تلمتری

یک فیلد و تعداد پکت‌های اخیر را انتخاب کنید

Spec و خطاها

مشخصات OpenAPI در آدرس زیر موجود است:

https://gateway.spaceomid.com/iot/public/v1/openapi.json

400 — پارامتر نامعتبر
404 — پکت یافت نشد
429 — عبور از حد مجاز
502 — خطای سرویس بالادستی