Сущности

Найдите сущности и связанные с ними публикации

Сущности обозначают людей, компании, места, события и продукты, найденные в публикациях. Методы ниже позволяют найти сущность, оценить число упоминаний и получить связанные материалы.

#Список сущностей

GET/v1/entitiesAPI key

Параметры запроса

searchstringнеобязательный: Часть имени без учёта регистра.
entity_typestringнеобязательный: Тип сущности, например SportsTeam.
min_scorenumberнеобязательныйпо умолчанию 0.0: Минимальное значение unified_score.
limitintegerнеобязательныйпо умолчанию 50: Размер страницы от 1 до 200.
offsetintegerнеобязательныйпо умолчанию 0: Число пропущенных элементов.

curl

curl "https://dstrends.com/api/v1/entities?search=ballers&entity_type=SportsTeam&min_score=0.5&limit=2" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "entities": [
    {
      "name": "Example City Ballers",
      "normalized_name": "example city ballers",
      "unified_score": 0.87,
      "entity_types": ["Organization", "SportsTeam"],
      "wikipedia_url": "https://en.wikipedia.org/wiki/Example_City_Ballers",
      "kg": {
        "id": "/g/11abc",
        "name": "Example City Ballers"
      }
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0
}

Набор полей может расширяться. Основные поля для сопоставления: normalized_name, entity_types, unified_score и kg.

#Популярные сущности

GET/v1/entities/trendingAPI key

Параметры запроса

regionstringобязательный: Двухбуквенный код страны.
periodstringнеобязательныйпо умолчанию 24h: 1h, 6h, 24h или 7d.
entity_typestringнеобязательный: Оставить сущности одного типа.
langstringнеобязательный: Оставить публикации на выбранном языке.
limitintegerнеобязательныйпо умолчанию 20: Число результатов от 1 до 100.

curl

curl "https://dstrends.com/api/v1/entities/trending?region=US&period=24h&limit=2" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "region": "US",
  "period": "24h",
  "trending_entities": [
    {
      "name": "Example City Ballers",
      "mentions_in_period": 58,
      "articles_in_period": 21,
      "top_article": {
        "title": "Finals recap: an instant classic",
        "domain": "example-sports.com"
      }
    }
  ]
}

Список сортируется по mentions_in_period. Если за период нет совпадений, массив будет пустым.

#Одна сущность

GET/v1/entities/{entity_name}API key

Параметры пути

entity_namestringобязательный: Нормализованное имя. Пробелы нужно кодировать, например Example%20City%20Ballers.

curl

curl "https://dstrends.com/api/v1/entities/Example%20City%20Ballers" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "name": "Example City Ballers",
  "normalized_name": "example city ballers",
  "unified_score": 0.87,
  "entity_types": ["Organization", "SportsTeam"],
  "kg_id": "/g/11abc",
  "articles_count": 21
}

Если сущность не найдена или недоступна ключу, API вернёт 404.

#Публикации по сущности

GET/v1/entities/{entity_name}/articlesAPI key

Параметры запроса

entity_namestringобязательный: Имя сущности в адресе.
limitintegerнеобязательныйпо умолчанию 50: Размер страницы от 1 до 200.
offsetintegerнеобязательныйпо умолчанию 0: Число пропущенных публикаций.

curl

curl "https://dstrends.com/api/v1/entities/Example%20City%20Ballers/articles?limit=2" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "entity_name": "Example City Ballers",
  "articles": [
    {
      "url_id": "b3f1c2a0-...",
      "url": "https://example-sports.com/finals-recap",
      "title": "Finals recap: an instant classic",
      "domain": "example-sports.com",
      "unified_score": 0.87
    }
  ],
  "total": 21
}