Globale Parameter
Parameter, die für jeden Piloterr-API-Endpunkt verfügbar sind.
Diese Parameter können mit jedem API-Endpunkt verwendet werden.
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
x_api_key | string | - | Veraltet. Die API liest den Schlüssel auch aus diesem Query-Parameter, aber URLs landen in Server- und Proxy-Logs, im Browserverlauf und im Referer-Header. Senden Sie den Schlüssel stattdessen im x-api-key-Header. |
soft_fail | boolean | false | Wenn true, gibt die API auch im Fehlerfall HTTP 200 zurück, mit der Meldung im Feld error. Abgerechnet wird nach den üblichen Regeln: Fehler bleiben kostenlos. |
is_async | boolean | false | Wenn true, wird die Anfrage asynchron verarbeitet. Die Antwort enthält eine job_id, die Sie über /v1/jobs/{job_id} abfragen. |
fields | string | - | Komma-getrennte Liste der Felder, die in der Antwort enthalten sein sollen. Unterstützt verschachtelte Felder mit Punktnotation. |
Feldfilterung
Verwenden Sie den fields-Parameter, um nur die Daten zurückzubekommen, die Sie wirklich brauchen. Antworten werden kleiner, schneller heruntergeladen und einfacher zu parsen. Besonders nützlich, wenn Ihre Plattform eine Payload-Größenbegrenzung hat (Make.com, Zapier, Lambdas mit wenig Speicher usw.).
Syntax
Übergeben Sie fields als kommagetrennte Liste. Verwenden Sie einen Punkt (.), um in verschachtelte Objekte hineinzugehen.
- Top-Level-Felder werden mit ihrem Namen aufgeführt:
fields=name,founded. - Verschachtelte Felder verwenden Punktnotation:
fields=address.city,address.country. - Leerzeichen rund um Kommas werden ignoriert:
fields=name, foundedfunktioniert genauso. - Unbekannte Feldnamen werden stillschweigend ignoriert, es wird kein Fehler zurückgegeben.
Top-Level-Felder auswählen
Behalten Sie nur die Top-Level-Schlüssel, die Sie interessieren. Die ursprüngliche Struktur bleibt für die behaltenen Felder erhalten.
curl -X GET "https://api.piloterr.com/v2/{endpoint}?param=value&fields=name,founded,tagline" \
-H "x-api-key: YOUR_API_KEY"Antwort:
{
"name": "Example",
"founded": "2020",
"tagline": "Just an example"
}Verschachtelte Felder auswählen
Verwenden Sie die Punktnotation, um in verschachtelte Objekte zu gelangen. Nur die angeforderten Unterfelder werden zurückgegeben, der Rest des Eltern-Objekts wird verworfen. Punktnotation funktioniert auch für Objekte in Arrays: ?fields=team.name behält den name jedes Elements in team.
curl -X GET "https://api.piloterr.com/v2/{endpoint}?param=value&fields=name,location.city,location.country" \
-H "x-api-key: YOUR_API_KEY"Antwort:
{
"name": "Example",
"location": {
"city": "Paris",
"country": "France"
}
}Gut zu wissen
- Die Filterung passiert nach dem Abruf der Daten: Sie reduziert nicht die Credit-Kosten des Aufrufs. Sie reduziert Antwortgröße, Parsing-Zeit und Bandbreite.
- Top-Level-Schlüssel, die nicht in
fieldsaufgeführt sind, werden aus der Antwort entfernt. Wenn Sie verschachtelte Felder aufführen, bleibt das übergeordnete Objekt automatisch erhalten. fieldskann frei mit anderen Parametern wiesoft_failoderis_asynckombiniert werden.
Soft-Fail-Modus
Behandeln Sie Fehler elegant, indem Sie immer einen 200-Statuscode erhalten.
Fügen Sie soft_fail=true zu jeder Anfrage hinzu, um auch im Fehlerfall HTTP 200 zu erhalten.
Fehler werden weiterhin in Ihrem Dashboard protokolliert und nach den Standardregeln abgerechnet.
Anwendungsfälle
- Systeme, die Nicht-200-Codes als fatal behandeln (Make.com, Zapier)
- Eigene Fehlerbehandlung in Ihrer Anwendung
- Konsistente Fehlerbehandlung über mehrere Integrationen hinweg
Hinweis für Make.com-Nutzer: Standardmäßig stoppen Make.com-Szenarien mit einem Fehler, wenn sie einen HTTP-Statuscode 404 oder 500 erhalten. Mit soft_fail=true läuft Ihr Szenario weiter, auch wenn die API einen Fehler zurückgibt, sodass Sie ihn in nachfolgenden Modulen behandeln können.
Beispiel
curl -X GET "https://api.piloterr.com/v2/{endpoint}?param=invalid&soft_fail=true" \
-H "x-api-key: YOUR_API_KEY"{
"error": "Not Found"
}Asynchroner Modus
Für lange laufende Anfragen verwenden Sie den asynchronen Modus, um Timeouts zu vermeiden.
Fügen Sie is_async=true hinzu, um sofort eine job_id zu erhalten.
So funktioniert es
- Anfrage mit
is_async=truesenden - Eine
job_iderhalten /v1/jobs/{job_id}abfragen, um das Ergebnis zu erhalten
# Schritt 1: Job starten
curl -X GET "https://api.piloterr.com/v2/{endpoint}?param=value&is_async=true" \
-H "x-api-key: YOUR_API_KEY"
# Antwort: { "job_id": "abc123..." }
# Schritt 2: Ergebnis abrufen
curl -X GET "https://api.piloterr.com/v1/jobs/abc123..." \
-H "x-api-key: YOUR_API_KEY"Das Abfragen ist kostenlos. Fragen Sie alle paar Sekunden ab und verlängern Sie bei langen Jobs, etwa großen Downloads, die mehrere Stunden dauern können, die Abstände (bis zu einer Minute). progress geht von 0 bis 100, und der Job ist beendet, wenn status CompletedJob, Error, NotFound oder BadRequest ist.
Siehe Statuscodes für Antwortcodes, Best Practices für Integrationshinweise und Fehlerbehandlung für Retry-Strategien.