Hiring Lab API

Indeed Hiring Labの労働市場データを分析・調査用途で取得します。

 

法的注意

本APIおよびそのドキュメントを使用して連携を構築することにより、Indeedの利用規約に同意したものとみなされます。

Hiring Lab APIと連携する

Hiring Lab APIと連携するには、認証用のAPI keyを取得します。

APIキーを取得する

Indeedは、Hiring Labデータへのアクセスを必要とするパートナーと研究者にAPI keyを発行します。

API keyをリクエストするには、次の手順を実行します。

1. hiring-lab-api@indeed.comに、利用目的と組織情報を記載したメールを送信します。
2. Indeedがリクエストを審査し、API keyを発行します。
3. IndeedがAPI keyをメールで送信します。

API keyは安全に保管してください。クライアント側コードに埋め込んだり、バージョン管理にコミットしたりしないでください。

リクエストを認証する

Hiring Lab APIへのすべてのGraphQL requestで、Indeed-API-Key headerにAPI keyを含めます。

curl -X POST 'https://apis.indeed.com/graphql' \
  -H 'Content-Type: application/json' \
  -H 'Indeed-API-Key: YOUR_API_KEY' \
  --data-raw '{
    "query": "query { findHiringLabPostingsPublic(first: 10, input: { filter: { country: [\"US\"] } }) { edges { node { ... on HiringLabNationalPosting { date indexSa } } } } }"
  }'

YOUR_API_KEYを実際のAPI keyに置き換えます。

Referer headerを追加する

セキュリティフィルターでブロックされないように、requestにReferer headerを含めます。このheaderは、API callを行うdomainを識別します。

curl -X POST 'https://apis.indeed.com/graphql' \
  -H 'Content-Type: application/json' \
  -H 'Indeed-API-Key: YOUR_API_KEY' \
  -H 'Referer: https://your-domain.com' \
  --data-raw '{
    "query": "query { findHiringLabPostingsPublic(first: 10, input: { filter: { country: [\"US\"] } }) { edges { node { ... on HiringLabNationalPosting { date indexSa } } } } }"
  }'

https://your-domain.comを実際のdomainまたはservice identifierに置き換えます。

連携をテストする

簡単なqueryでAPI keyをテストします。

curl -X POST 'https://apis.indeed.com/graphql' \
  -H 'Content-Type: application/json' \
  -H 'Indeed-API-Key: YOUR_API_KEY' \
  -H 'Referer: https://your-domain.com' \
  --data-raw '{
    "query": "query { findHiringLabPostingsPublic(first: 5, input: { filter: { country: [\"US\"], postingType: TOTAL } }) { edges { node { ... on HiringLabNationalPosting { id date country { countryCode countryName } postingType indexSa indexNsa } } cursor } pageInfo { hasNextPage } } }"
  }'

requestが成功すると、求人投稿データが返されます。

{
  "data": {
    "findHiringLabPostingsPublic": {
      "edges": [{
        "node": {
          "id": "...",
          "date": "2024-10-01",
          "country": {
            "countryCode": "US",
            "countryName": "United States"
          },
          "postingType": "TOTAL",
          "indexSa": 102.5,
          "indexNsa": 103.2
        },
        "cursor": "..."
      }],
      "pageInfo": {
        "hasNextPage": true
      }
    }
  }
}

認証エラーを処理する

API keyが欠落している、または無効な場合、Indeedは401 Unauthorizedエラーを返します。

requestにReferer headerが含まれていない場合、セキュリティフィルターによりrequestがブロックされる可能性があります。domainまたはserviceを識別するReferer headerを含めてください。

Hiring Lab scope外のAPIを呼び出すと、IndeedはFORBIDDENエラーを返します。

{
  "errors": [{
    "message": "The client doesn't have access to any requested field from '[API NAME]'.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }],
  "data": {
    "[value]": null
  }
}

queryがHiring Lab API queryのみを使用していることを確認してください。対象はfindHiringLabPostingsPublic、findHiringLabRemotePublic、findHiringLabWagesPublic、findHiringLabAiPublic、および関連metadata queryです。

Hiring Lab APIの概要

Hiring Lab APIを使用して、Indeed Hiring Labがdata.indeed.comで公開するデータへアクセスできます。このAPIは、求人投稿の動向、賃金成長、リモートワークの傾向、AI関連の求人機会など、包括的な労働市場データを提供します。

研究者、政策担当者、エコノミスト、アナリストは、Hiring Lab APIを呼び出して信頼性の高い労働市場データを収集できます。Hiring Lab APIは、データセットごとに異なる粒度と頻度でデータを提供します。

主な機能

• 包括的なカバレッジ: 複数の国と地域を対象にできます。
• 複数の粒度: 全国、地域、業種別のデータを取得できます。
• リアルタイム更新: 日次および月次のデータ更新を受け取れます。
• カーソルベースのページネーション: 大規模なデータセットを効率的にページングできます。
• 公開データと非公開データ: 認証に応じてアクセスレベルを選択できます。

利用可能なデータセット

Hiring Lab APIは、次のコアデータセットへのアクセスを提供します。

Hiring Lab API datasets

Dataset	Description	Granularity			Frequency
		National	Regional	Sectoral	Daily	Monthly
Job Postings	季節調整別の求人投稿インデックスです。	✔	✔	✔	✔
Remote Work	リモートおよびハイブリッドの求人投稿と検索です。	✔		✔	✔
Wage Growth	求人投稿に基づく前年比の賃金成長です。	✔		✔		✔
AI Jobs	生成AIを含むAI関連の求人投稿です。	✔			✔

求人投稿データを取得する

求人投稿インデックスデータを取得するには、findHiringLabPostingsPublic queryを呼び出します。

query {
  findHiringLabPostingsPublic(first: 50, input: {
    filter: {
      country: ["US"],
      postingType: TOTAL
    }
  }) {
    edges {
      node {
        ...on HiringLabNationalPosting {
          id
          date
          country {
            countryCode
            countryName
          }
          postingType
          indexSa
          indexNsa
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

地域別の求人投稿データ

地域別の求人投稿データを取得するには、同じqueryを呼び出して、geographyとregionでfilterします。

query {
  findHiringLabPostingsPublic(input: {
    filter: {
      country: ["US"],
      geography: STATES,
      region: ["California", "Texas"]
    }
  }) {
    edges {
      node {
        ...on HiringLabRegionalPosting {
          date
          country {
            countryCode
            countryName
          }
          region {
            regionCode
            regionName
          }
          geography {
            geography
          }
          indexSa
          indexNsa
        }
      }
    }
  }
}

業種別の求人投稿データ

業種別の求人投稿データを取得するには、次のqueryを使用します。

query {
  findHiringLabPostingsPublic(input: {
    filter: {
      country: ["US"],
      sector: ["Technology", "Healthcare"]
    }
  }) {
    edges {
      node {
        ...on HiringLabSectoralPosting {
          date
          country {
            countryCode
            countryName
          }
          sector {
            sectorCode
            sectorName
          }
          indexSa
          indexNsa
        }
      }
    }
  }
}

リモートワークデータを取得する

リモートワークの傾向へアクセスするには、findHiringLabRemotePublic queryを呼び出します。

query {
  findHiringLabRemotePublic(input: {
    filter: {
      country: ["US"],
      metric: POSTINGS
    }
  }) {
    edges {
      node {
        ...on HiringLabNationalRemote {
          date
          country {
            countryCode
            countryName
          }
          metric
          remoteShare
        }
      }
    }
  }
}

remoteShare fieldは、リモートまたはハイブリッドの求人投稿の割合を返します。POSTINGSまたはSEARCHESでfilterするには、metric parameterを含めます。

賃金成長データを取得する

賃金成長データを取得するには、findHiringLabWagesPublic queryを呼び出します。

query {
  findHiringLabWagesPublic(input: {
    filter: {
      country: ["US"]
    }
  }) {
    edges {
      node {
        ...on HiringLabNationalWage {
          date
          country {
            countryCode
            countryName
          }
          wageGrowthYoy
          wageGrowth3Ma
        }
      }
    }
  }
}

responseには次の内容が含まれます。

• wageGrowthYoy: 掲載賃金の前年比変化
• wageGrowth3ma: 前年比変化の3か月ラグ移動平均

AI求人投稿データを取得する

AI関連の求人動向へアクセスするには、findHiringLabAiPublic queryを使用します。

query {
  findHiringLabAiPublic(input: {
    filter: {
      country: ["US"]
    }
  }) {
    edges {
      node {
        ...on HiringLabNationalAI {
          date
          country {
            countryCode
            countryName
          }
          aiShare
        }
      }
    }
  }
}

responseには、AI関連の求人投稿の割合を示すaiShareが含まれます。

利用可能なデータカバレッジを一覧表示する

データカバレッジがある国を一覧表示する

query {
  findHiringLabCountriesPublic(input: {
    filter: {
      datasetId: "job_postings",
      granularity: NATIONAL
    }
  }) {
    results {
      countryCode
      countryName
    }
  }
}

利用可能な業種を一覧表示する

query {
  findHiringLabSectorsPublic(input: {
    filter: {
      datasetId: "job_postings",
      country: "US"
    }
  }) {
    results {
      sectorCode
      sectorName
    }
  }
}

利用可能な地理区分を一覧表示する

query {
  findHiringLabGeographiesPublic(input: {
    filter: {
      datasetId: "job_postings",
      country: "US"
    }
  }) {
    results {
      geography
    }
  }
}

利用可能な地域を一覧表示する

query {
  findHiringLabRegionsPublic(input: {
    filter: {
      datasetId: "job_postings",
      country: "US",
      geography: STATES
    }
  }) {
    results {
      regionCode
      regionName
    }
  }
}

すべてのデータセットを一覧表示する

query {
  allHiringLabDatasetsPublic {
    results {
      id
      name
      description
      granularity
      frequency
    }
  }
}

ページネーション

Hiring Lab APIは、大規模なデータセットを効率的にページングするために、カーソルベースのページネーションを使用します。first parameterで1ページあたりの件数を指定し（最大50件）、次のページを取得するには、after parameterにcursor valueを渡します。

query {
  findHiringLabPostingsPublic(first: 50, after:
    "cursor_value_from_previous_response", input: {
      filter: {
        country: ["US"]
      }
    }) {
    edges {
      node {
        #...your fields
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

エラーをトラブルシューティングする

GraphQLへ到達する前に発生するOAuthエラーについては、Troubleshoot OAuth errorsをご覧ください。

GraphQLエラーについては、Troubleshoot GraphQL errorsをご覧ください。

Hiring Lab APIの用語定義については、Hiring Lab API glossaryをご覧ください。

Hiring Lab API FAQs

すべての求人投稿インデックスは2020年2月1日をベースライン（= 100）として使用しています。このベースラインにより、国や期間を超えた一貫した比較が可能になります。

Hiring Lab API

季節調整済み（SA）インデックスは、基調的なトレンドを示すために典型的な季節パターンを除去します。非季節調整（NSA）インデックスは、年末年始の採用などの通常の季節変動を含む生データを示します。

Hiring Lab API

• 求人投稿およびリモートワークデータ：毎日更新
• 賃金上昇データ：毎月更新
• AI求人投稿データ：毎日更新

Hiring Lab API

カバー範囲はデータセットによって異なります。各データセットと粒度レベルで利用可能な国を確認するには、findHiringLabCountriesPublicクエリを使用してください。

Hiring Lab API

過去のデータを取得するには、カーソルベースのページネーションを使用してください。必要なフィルタを設定し、前回のレスポンスのafterパラメータとカーソル値を使用して結果をページネーションしてください。

Hiring Lab API

リクエストあたりの最大結果数は50件です。より大きなデータセットを取得するにはページネーションを使用してください。

Hiring Lab API

APIは時系列順でデータを返します。必要な期間にフィルタするには、アプリケーションロジックでページネーションと日付フィールドを使用してください。

Hiring Lab API

 

このページは役に立ちましたか？