# /openwork/companies/search

`POST /api/openwork/companies/search`

Price: 10 credits

Search employers on OpenWork (openwork.jp), the Japanese employee review site, by company name, industry and prefecture, ordered by review count, overall employee score or one of the eight category scores. Each company comes with its overall score, industry, and its numbers of reviews, salary reviews, questions, jobs and followers.

## How to use it

A search returns at most 500 companies, so narrow by industry or prefecture for more. Score orders carry each company's rank, and category-score orders also the ranked category score. Pass a company id to openwork/companies for the full profile.

## Parameters

- `access-token` (string, required)

## Request body

- `timeout` (integer) — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
- `count` (integer, required) — Max number of companies to return (min: 1; max: 500)
- `keyword` (string, nullable) — Words in the company name (examples: "メルカリ", "トヨタ"; minLength: 1)
- `industry` (string, nullable) — Company industry (one of: "銀行(都市・信託・政府系)、信金", "証券会社、投資ファンド、投資関連", "生命保険、損害保険", "投信投資顧問", "クレジット、信販、リース", "商品取引", "消費者金融、事業者金融", "その他金融関連", "コンサルティング、シンクタンク", "監査法人、税理士法人、法律事務所", "SIer、ソフト開発、システム運用", "インターネット", "通信、ISP、データセンター", "制御システム、組込みソフトウェア", "その他ＩＴ・通信関連", "総合商社", "総合電機、家電、AV機器", "自動車、自動車部品、輸送機器", "コンピュータ、通信機器、OA機器関連", "半導体、電子、精密機器", "重電、産業用電気機器、プラント関連", "鉄鋼、非鉄金属", "機械関連", "化学、石油、ガラス、セラミック", "食品、飲料", "日用品、化粧品", "ファッション、アパレル、繊維", "インテリア、雑貨、文具、スポーツ", "印刷、紙・パルプ、書籍、パネル", "住宅設備、建材、エクステリア", "ゲーム関連、玩具", "その他メーカー・商社", "医薬品、医療機器", "治験、臨床試験、医薬営業受託", "調剤薬局", "バイオ関連", "病院、医療機関", "その他医療・医薬サービス", "放送、出版、新聞、映像、音響", "広告代理店、PR、SP、デザイン", "その他マスコミ関連", "小売(百貨店・専門・CVS・量販店)", "通信販売", "物品レンタル", "フードサービス、飲食", "旅行、ホテル、旅館、レジャー", "冠婚葬祭", "人材サービス", "コールセンター、業務請負", "情報サービス、リサーチ", "教育、研修サービス", "警備、メンテナンス", "介護、福祉関連サービス", "美容、エステ、リラクゼーション", "環境サービス", "受託製造(設計・開発・加工)", "その他小売、外食、レジャー、サービス", "電力、ガス、エネルギー", "航空、鉄道、運輸、倉庫", "不動産関連、住宅", "建築、土木、設備工事", "官公庁", "独立行政、社団、財団、学校法人", "非政府組織(NGO)、非営利団体(NPO)", "農業、林業、水産、畜産", "鉱業")
- `prefecture` (string, nullable) — Prefecture of the company (one of: "北海道", "青森県", "岩手県", "宮城県", "秋田県", "山形県", "福島県", "茨城県", "栃木県", "群馬県", "埼玉県", "千葉県", "東京都", "神奈川県", "新潟県", "富山県", "石川県", "福井県", "山梨県", "長野県", "岐阜県", "静岡県", "愛知県", "三重県", "滋賀県", "京都府", "大阪府", "兵庫県", "奈良県", "和歌山県", "鳥取県", "島根県", "岡山県", "広島県", "山口県", "徳島県", "香川県", "愛媛県", "高知県", "福岡県", "佐賀県", "長崎県", "熊本県", "大分県", "宮崎県", "鹿児島県", "沖縄県", "海外")
- `sort` (string) — Result order (default: "review_count"; one of: "review_count", "score", "compensation_score", "morale_score", "openness_score", "mutual_respect_score", "young_growth_score", "talent_development_score", "compliance_score", "evaluation_fairness_score")

## Response

### 200 — Successful Response

- `@type` (string) (default: "OpenworkCompanySearchResult")
- `id` (string, required)
- `url` (string, required)
- `name` (string, nullable)
- `image` (string, nullable)
- `rank` (integer, nullable)
- `score` (number, nullable)
- `ranking_metric` (string, nullable)
- `ranking_score` (number, nullable)
- `industry_name` (string, nullable)
- `review_count` (integer, nullable)
- `salary_review_count` (integer, nullable)
- `question_count` (integer, nullable)
- `job_count` (integer, nullable)
- `follower_count` (integer, nullable)

## Errors

### 422 — Validation Error

An unknown industry, prefecture or sort value

What to do: Check the fields against this schema. A URN with the wrong prefix is the most common cause.

- `detail` (array)
  - `loc` (array, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any)
  - `ctx` (object)

### 408

The request ran past its time limit

What to do: Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.

### 412

The entity was not found, or a precondition failed

What to do: Retrying will not help: either the entity does not exist, or the input points at a different one.

### 429

Too many requests: a rate limit or a usage window is exhausted

What to do: When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.

### 500

Something broke on our side

What to do: Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.

### 529

Rate limit reached, or the endpoint is overloaded

What to do: Wait at least 30 seconds, then retry.

## Response envelope

Success: Array of objects (may be empty if no results)

Error: Error may coexist with partial results if it occurs mid-execution. Check X-Error header and status code.

Every response carries these headers:

- `X-Error` — Error message text (present only on error)
- `X-Request-ID` — Unique request identifier
- `X-Execution-Time` — Execution time in seconds
- `X-Result-Count` — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
- `X-Total-Available-Results` — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
- `X-Warning` — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
- `X-Retry-After` — Seconds to wait before retrying. Present only on 429.