Fastah API
Contract version gen2-4.0.0, rendered from the flattened Fastah worker OpenAPI specification. Authentication and server origins are supplied by the deployment and are not declared in this worker contract.
Endpoints
GET/ip
Operation — · ip-location
Responses
| Status | Body | Description |
|---|---|---|
200 | — | Returns the IP address of the client making the request. |
GET/ip/{ip}
Operation ip-location-lookup · ip-location
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ip | path | string | Yes | An IP address. Try 202.94.72.116, or just 'auto' for IP auto-detection. |
Responses
| Status | Body | Description |
|---|---|---|
200 | restIpElement | Returns the approximate geo-coordinates, location name, country, and time zone of the specified IP. |
400 | problemResponseError | This response is returned when a malformed or invalid IP address was specified in the request. |
POST/ip/batch
Operation ip-location-lookup-batch · ip-location
Request body: restIpBatchRequest (required)
Responses
| Status | Body | Description |
|---|---|---|
200 | restIpBatchResponse | Ordered per-IP batch results. |
400 | problemResponseError | Batch validation failure. |
POST/geofeeds/place-search
Operation rfc8805-place-search · place-search
Request body: restRfc8805PlaceSearchBatch (required)
Responses
| Status | Body | Description |
|---|---|---|
200 | restRfc8805PlaceSearchResults | Ordered per-row place-search results. |
400 | problemResponseError | Batch validation failure. |
GET/docs
Operation get-docs · docs
Responses
| Status | Body | Description |
|---|---|---|
200 | — | Documentation page content. |
Data schemas
restIpElement
Per-IP lookup result.
| Field | Type | Required | Description |
|---|---|---|---|
ip | string | Yes | The IP address described by this response. |
isGeolocatable | boolean | Yes | Indicates whether the IP address can be geolocated. False for non-globally-routable IPs and for infrastructure IPs without a meaningful location. |
approxGeo | approxGeo | No | — |
prefixDetails | prefixDetails | No | — |
explanation | string | No | Human-readable explanation, including an error message when the lookup failed. |
expiresAt | integer · int64 | Yes | Cache TTL: do not use or cache this response after this Unix epoch time in milliseconds. |
restIpBatchRequest
Batch request for IP lookups.
| Field | Type | Required | Description |
|---|---|---|---|
ips | string[] | Yes | 1 to 1000 IPv4/IPv6 addresses. |
restIpBatchResponse
Batch response for IP lookups.
| Field | Type | Required | Description |
|---|---|---|---|
results | restIpElement[] | Yes | Per-IP lookup results, in the same order as the input ips array. |
restRfc8805PlaceSearchBatch
Batch request for RFC 8805 place search.
| Field | Type | Required | Description |
|---|---|---|---|
rows | rfc8805RowPlaceSearchParams[] | Yes | Array of rows for the batch place search. |
restRfc8805Location
Location information for RFC 8805 place search results.
Schema type: approxGeo & object
restRfc8805RowPlaceResult
Individual row result for RFC 8805 place search.
| Field | Type | Required | Description |
|---|---|---|---|
rowKey | string | Yes | Opaque caller-assigned key used to deduplicate and correlate a row. It is unique within a batch and echoed unchanged; it is not required to be a hash. |
matches | restRfc8805Location[] | Yes | Ordered best-first matches. Empty for non-matched or do-not-geolocate rows. |
isExplicitlyDoNotGeolocate | boolean | Yes | True when the row's country is empty or ZZ. |
message | string | Yes | Human-readable explanation. |
restRfc8805PlaceSearchResults
Results for RFC 8805 place search.
| Field | Type | Required | Description |
|---|---|---|---|
results | restRfc8805RowPlaceResult[] | Yes | Exactly one result per input row, in input order and correlated by rowKey. |
approxGeo
Approximate geographic location for this IP address. An accuracy radius in kilometers around the longLat coordinates is provided to indicate confidence in the location estimate.
| Field | Type | Required | Description |
|---|---|---|---|
countryName | string | Yes | Country name as a display string |
countryCode | string | Yes | ISO 3166-1 alpha-2 country code |
flagEmoji | string | Yes | The flag emoji corresponding to the country code (e.g. 🇺🇸 for US, 🇮🇳 for IN) |
sovereignCountryCode | string | Yes | ISO 3166-1 alpha-2 code of the sovereign country. Equals countryCode for independent nations. Differs for dependent territories, e.g. 'US' when countryCode is 'UM' (US Minor Outlying Islands), or 'GB' when countryCode is 'IO' (British Indian Ocean Territory). |
stateName | string | Yes | Name of the state, province, or top-level administrative subdivision of a country. May be empty for smaller countries without a commonly-used subdivision, or when placeType is 'country'. |
stateCode | string | Yes | ISO 3166-2 code, if available, of the state, province, or top-level administrative subdivision. May be empty for countries without a commonly-used subdivision code. |
placeName | string | Yes | Name of the resolved location, which may be a city, region, or country depending on placeType |
placeType | city | region | country | Yes | The geographic granularity of this location result. A 'city' is the most precise, 'region' indicates a state or province, and 'country' means a country or territory. |
longLat | number · double[] | Yes | Longitude, Latitude representing the approximate geographical center, to be interpreted together with accuracyRadius - the radius in kilometers around this point as a confidence region. |
boundingBox | number · double[] | Yes | The rectangular bounding box of the matched place as [minLong, minLat, maxLong, maxLat], providing the geographic extent of the resolved location. |
accuracyRadiusKm | integer | Yes | Confidence radius in kilometers around the center point geo-coordinates in longLat |
tz | string | Yes | IANA time zone identifier for this location. May be empty for large-area regions or countries that span multiple time zones. |
h3Cells | string[] | Yes | Array of Uber H3 hexagonal cell indices that cover the geographic extent of this matched place, enabling efficient spatial indexing and hierarchical geofencing. |
placeIdGeonames | integer · int64 | Yes | A stable place ID - in this case within the Geonames.org place names database |
continentCode | string | Yes | 2-letter continent code |
asnDetails
Details about the Autonomous System and its associated organization.
| Field | Type | Required | Description |
|---|---|---|---|
asn | integer · uint32 | No | The autonomous system number (ASN). |
asnName | string | No | The registered name of the Autonomous System. |
orgId | string | No | The identifier of the organization associated with the Autonomous System. |
orgName | string | No | The registered name of the organization associated with the Autonomous System. |
originDetails
Details about the origin of the IP network prefix, including the ASN and its associated organization.
| Field | Type | Required | Description |
|---|---|---|---|
asns | asnDetails[] | No | The autonomous system numbers (ASNs) associated with the IP network prefix. |
prefixDetails
Details about the IP network prefix containing the IP address.
| Field | Type | Required | Description |
|---|---|---|---|
cidr | string | No | The CIDR notation of the IP network prefix containing the IP address. |
origins | originDetails[] | No | The origins of the IP network prefix, which may include multiple ASNs and their associated details. |
problemResponseError
The error response schema.
| Field | Type | Required | Description |
|---|---|---|---|
ip | string | No | The IP address which is described in this response |
message | string | Yes | A description of what went wrong |
rfc8805SearchMode
Fastah place-search preference. Auto returns the best available suggestion; prefer_larger_area favors a region or country when zooming out; prefer_larger_population_center favors a regional or national population center.
Schema type: auto | prefer_larger_area | prefer_larger_population_center
rfc8805RowPlaceSearchParams
Privacy-minimized RFC 8805 row fields used for Fastah place-search suggestions. This model never includes an IP prefix, feed URL or comment, publisher identity, or RDAP data.
| Field | Type | Required | Description |
|---|---|---|---|
rowKey | string | Yes | Opaque caller-assigned key used to deduplicate and correlate a row. It is unique within a batch and echoed unchanged; it is not required to be a hash. |
countryCode | string | Yes | RFC 8805 country field. Fastah trims whitespace and matches alpha-2 values case-insensitively. Empty or ZZ means do not geolocate; other semantic invalidity is reported for this row. |
regionCode | string | No | Optional RFC 8805 region field. Fastah trims whitespace, accepts case-insensitive ISO 3166-2-style values, and reports malformed or country-mismatched values for this row. |
cityName | string | No | Optional RFC 8805 city field. Fastah trims edge whitespace; commas and line breaks are reported as invalid for this row. |
searchMode | rfc8805SearchMode | No | — |
Source
OpenAPI 3.0.0. Generated from gen2/openapi/worker/specs/worker-spec-oas3-flattened.jsonin the Fastah monorepo.