Three Changes You Need to Make for Search 2.0 API
I’m a Censys Search API user, and I want to upgrade to Search 2.0.
If this is you, here are the three changes you need to make to your API client in order to begin querying hosts in the all new Censys Search 2.0.
1. Update API Endpoints
Host search and lookup has moved to a new URL with new paths and HTTP methods.
-
Method:
GET
-
Base URL:
https://search.censys.io
. -
Path:
/api/v2/hosts
-
Endpoints:
-
/search
— Search for hosts by submitting a query using the new Censys Search Language. -
/{ip-address}
— Look up a host by its IP address. -
/{ip-address}/names
— Retrieve a list of domain-style names that a host responded to during a Censys scan. -
/aggregate
— See a breakdown of hosts (that match a provided search query) according to their values for a field that you select.
-
Visit the Censys Search 2.0 API documentation for details on each endpoint.
2. Update Search Queries
In order to translate search queries used on Censys' legacy host dataset to work in Search 2.0, you must change field names to reflect the new, improved host schema and adjust syntax to use the more powerful Censys Search Language.
Schema Changes
Host data is now modeled to reflect improvements in Censys scanning technology, so the name of almost every field you formerly queried has changed, although keys still use dot notation to show their nested structure (e.g., services.http.response.body
).
For more information, you can read about the host data model or see some example queries translated, or just browse the entire schema.
Query Syntax
Search 2.0 also utilizes a new Censys Search Language. Read this introduction to learn how to:
-
Specify fields
-
Write queries that account for port-independent data
-
Use wildcards
-
Limit results to exact matches
-
Leverage boolean operators like
and
,or
andnot
3. Update Behavior to Perform Lookups on Search Hits
Unlike the v1 Search API endpoint, the 2.0 hosts/search
API endpoint does not accept a list of host fields to return as part of the response.
Instead, a static preview of each host matching the provided query is returned.
Your client must iterate through the results returned by the hosts/search
endpoint with calls to the hosts/{ip-address}
endpoint to extract all fields of interest.
Note
|
Search 2.0 query quotas and rate limits have been increased to account for this behavior change. You can see the rate limits that apply to your account here. |
Questions? Reach out to support@censys.io!
Comments
0 comments
Article is closed for comments.