요청 보내기

/v1/search는 검색창에 입력하는 것과 같은 쿼리에 몇 가지 파라미터를 더해 받습니다. GET과 POST 모두 지원하며, 어느 쪽이든 파라미터는 같습니다.

파라미터

이름	기본값	의미
`query`	필수	검색 문자열입니다. 웹사이트와 문법이 같습니다. 쿼리 문법을 참고하세요.
`page`	1	1부터 시작합니다.
`per_page`	100	요금제의 행 한도까지 지정할 수 있으며, `page × per_page`도 마찬가지입니다. 요금제는 쿼리 결과의 처음 N행까지만 제공하며, 페이지를 넘겨도 그 이상은 볼 수 없습니다(`400 page_too_deep`). 이 값은 `/v1/account`에서 `max_per_page`로 확인할 수 있습니다.
`snippets`	사용 안 함	`1`이면 일치한 텍스트를 포함합니다. 스니펫 할당량이 차감됩니다.
`format`	`json`	6가지 중 하나입니다. 응답 형식을 참고하세요.
`columns`	형식에 따라 다름	`domain`, `url`, `rank`, `ranked`, `snippets` 중 원하는 열을 쉼표로 구분해 지정합니다.
`delimiter`	`;` / 탭	`csv`와 `tsv`에 적용됩니다.
`header`	사용 안 함	`1`이면 `csv`와 `tsv`에 헤더 줄을 넣습니다.

GET

curl -H "Authorization: Bearer $KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&page=2&per_page=50"

쿼리는 반드시 URL 인코딩하세요. 따옴표, 슬래시, + 모두 의미가 있습니다.

POST

같은 파라미터를 JSON 본문으로 보냅니다. 쿼리가 길거나 구문이 여러 개일 때 사용하세요. 여러 줄짜리 쿼리를 URL에 넣으면 서버보다 훨씬 먼저 프록시와 클라이언트의 길이 제한에 걸립니다.

curl https://api.publicwww.com/v1/search \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": ["\"angular.min.js\"", "\"bootstrap.min.css\""],
          "per_page": 50,
          "snippets": true}'

구문 배열은 모든 구문이 포함되어야 한다는 뜻이며, query 문자열에서 줄 바꿈으로 구분한 것과 같습니다. 위 예시에서 첫 번째 구문이 있는 사이트는 278개이고, 두 구문이 모두 있는 사이트는 99개입니다.

JSON 타입을 인식합니다. 쿼리 문자열에서 1이 필요한 곳에 true를 쓸 수 있습니다. 같은 파라미터가 URL과 본문에 모두 있으면 본문의 값이 우선합니다.

응답

필드	의미
`total`	전체 인덱스에서 일치하는 사이트 수입니다. 추정치가 아닌 실제 개수입니다.
`total_pages`	`total`을 `per_page`로 나눈 값을 올림한 것입니다.
`returned`	이 페이지에 실제로 담긴 행 수입니다.
`truncated`	요금제의 공개 범위 한도 때문에 일부 행이 제외되었는지 여부입니다.
`took_ms`	검색에 걸린 시간(밀리초)입니다.
`results`	결과 행입니다.

행

필드	의미
`domain`	사이트입니다.
`url`	일치 항목이 발견된 페이지입니다. `depth:` 검색에서는 메인 페이지가 아닐 수 있습니다.
`rank`	순위이며, 낮을수록 인기가 많습니다. 순위가 없는 사이트는 `null`입니다.
`ranked`	`rank`가 `null`일 때만 `false`입니다.
`snippets`	`snippets=1`일 때만 포함됩니다. 최대 5개의 `{"text", "match"}` 쌍이며, `match`는 일치한 부분, `text`는 그 부분과 주변 문맥입니다.

페이지 나누기와 대량 조회

page로 페이지를 넘기거나, per_page를 크게 지정해 한 번에 모두 받을 수 있습니다. 최대값은 /v1/account의 max_per_page이며, 유료 요금제에서는 100만입니다. 별도의 내보내기 엔드포인트는 없습니다. 응답은 생성되는 대로 전송되므로, 100만 행을 보낸다고 해서 어딘가의 메모리에 100만 행을 한꺼번에 올려 두지 않습니다.

다음 응답 형식