응답 형식

검색 리소스는 하나이고, 응답 형식은 여섯 가지입니다. format=으로 선택하며, 기본값은 JSON입니다. 다른 형식은 모두 JSON을 기준으로 설명합니다.

`format`	Content-Type	구조
`json`	`application/json`	객체 하나이며, 결과는 배열에 담깁니다.
`ndjson`	`application/x-ndjson`	한 줄에 JSON 객체 하나씩입니다. 첫 줄은 메타데이터이며 `"object":"meta"`로 표시됩니다.
`xml`	`application/xml`	같은 문서를 XML로 표현하며, 각 행은 `<result>`입니다.
`csv`	`text/csv`	세미콜론으로 구분하며, 헤더 줄이 없습니다.
`tsv`	`text/tab-separated-values`	CSV와 같지만 탭으로 구분합니다.
`txt`	`text/plain`	한 줄에 URL 하나씩입니다.

jsonl도 ndjson의 다른 이름으로 인식합니다.

어떤 형식을 쓸까

메모리에 다 들어가는 양이라면 json을, 그렇지 않다면 ndjson을 쓰세요. ndjson은 전체를 감싸는 배열이 끝나기를 기다릴 필요가 없고, 메타데이터가 결과 행보다 먼저 도착하며, 나머지가 도착하는 동안 첫 번째 결과부터 처리를 시작할 수 있습니다. csv, tsv, txt는 스프레드시트, 셸 파이프라인, 그리고 기존 내보내기 URL을 쓰던 스크립트를 파서 변경 없이 옮길 때 적합합니다.

ndjson

{"object":"meta","query":"\"angular.min.js\"","page":1,"per_page":2,"total":278,"total_pages":139,"returned":2,"truncated":false,"took_ms":2}
{"domain":"imgbox.com","url":"https://imgbox.com/","rank":4187,"ranked":true}
{"domain":"angularjs.org","url":"https://angularjs.org/","rank":12376,"ranked":true}

열 선택하기

json과 xml은 모든 필드를 반환합니다. 반면 단순 텍스트 형식은 기본적으로 익숙한 열만 반환하므로, 기존 내보내기 URL에서 옮겨 오는 스크립트는 파서를 바꿀 필요가 없습니다.

요청	출력
`format=csv`	`imgbox.com;4187`
`format=csv&columns=url,rank`	`https://imgbox.com/;4187`
`format=csv&columns=domain`	`imgbox.com`
`format=txt`	`https://imgbox.com/`
`format=csv&snippets=1`	`imgbox.com;4187;the matching text`
`format=csv&header=1`	첫 줄에 `domain;rank` 헤더
`format=csv&delimiter=,`	`imgbox.com,4187`

columns는 모든 형식에서 작동합니다. 예를 들어 format=json에 columns=domain을 지정하면 그 필드만 담긴 객체를 반환합니다.

단순 텍스트 형식의 세부 사항

값에 구분자, 따옴표, 줄 바꿈이 들어 있어 행이 깨질 수 있을 때만 값을 따옴표로 묶습니다. 일반적인 domain;rank 출력에는 따옴표가 없습니다.
따옴표로 묶인 값 안의 따옴표는 CSV 규칙대로 두 번 씁니다.
스니펫은 목록이므로 ...로 이어 붙여 한 칸에 넣습니다.
순위가 없는 사이트는 순위 칸이 비어 있습니다. 이 형식에서는 이것이 null을 나타냅니다.
전체 개수는 행에 넣을 수 없으므로 X-Total-Results, X-Returned-Results, X-Truncated 헤더로 전달합니다. 이 헤더는 모든 형식에서 전송됩니다.

이 형식들은 새 API 고유의 직렬화 방식이며, 기존 내보내기를 다시 내놓은 것이 아닙니다. 구조는 일부러 익숙하게 맞췄지만, 바이트 단위까지 똑같은 출력을 보장하는 것은 기존 URL뿐입니다.

형식과 오류

csv, tsv, txt는 결과 행 전용 형식이므로, /v1/account에 이 형식을 요청하면 400 format_not_available이 반환됩니다. 오류 자체는 JSON으로, XML을 요청했다면 XML로 반환됩니다.

다음 할당량 및 속도 제한