Schülerkarriere API Dokumentation

Logo

Dokumentation für die Schülerkarriere API.

Neue URL für die Dokumentation: docs.schuelerkarriere.de

Inhaltsverzeichnis

Allgemein
Bugs
Filter/Query
Query limiting
Umgebungssuche/Umkreissuche
Fehler
Sorting
JSON oder XML
Endpunkte

Allgemein:

Die API ist über zwei Domains zu erreichen:

dev.api.schuelerkarriere.de ist nur für Testzwecke gedacht.

Dies ist eine JSON HTTP API. _XML wird teilweise unterstützt. Siehe hier. Es gibt keine garantie, dass XML richtig funktioniert._

Bugs:

Wenn sie einen Fehler in der API finden, erstellen sie bitte ein Issue in dieser Repository.
Bitte schicken sie keine E-Mail. Es ist einfacher alle Fehler an einem Ort zu bündeln. E-Mails gehen viel zu schnell unter.

E-Mail: [email protected]

Filter/Query

Jeder API Endpunkt gibt die Möglichkeit zu Filtern.

Es gibt zwei Möglichkeiten zu filtern:

Die erste Möglichkeit zu filtern geht über Query Parameter.

Um z.B alle Jobs, die den Status publish haben, zu bekommen, setzt man einfach den Query Parameter status auf publish: /jobs?status=publish

Um genau das Gegenteil zu erreichen, hängt man an den Query Parameter Namen folgendes an: [!]: /jobs?status[!]=publish

Alle weiteren Vergleichs Operatoren werden ähnlich verwendet.

Hier eine Liste an allen verfügbaren Vergleichs Operatoren:

Operator	Operator in der SK API
`=`	`=`
`!=`	`[!]`
`<`	`[<]`
`>`	`[>]`
`>=`	`[>=]`
`<=`	`[<=]`

Zwei Query Parameter mit dem gleichen Namen werden mit einem oder verbunden.
Also entspricht /jobs?status=publish&status=draft folgendem status = "publish" OR status = "draft"

Um ein verschachteltes Objekt zu Testen, kann man mit einem Punkt auf unter Eigenschaften zuzugreifen.

Beispiel:

Alle Jobs die einer Bestimmten Firma zugehören: /jobs?company.id=155

Die zweite Möglichkeit:

Man kann ein Realm Database Query über den q Parameter übergeben.

Mehr Informationen finden sie hier.

Note: Die Query muss URL Encoded werden.

Hier ein Beispiel: /jobs?q=status != "publish" AND status != "trash" -> Gibt alle Jobs mit dem Status draft zurück.

Query limiting

Es ist möglich die Rückgabe auf eine bestimmte Anzahl an Ergebnissen zu limitieren. Hierfür hängt den Query Parameter limit an die URL an.

Ein Beispiel:

Sie möchten nur 10 Jobs abfragen:

https://api.schuelerkarriere.de/jobs?limit=10

Umgebungssuche/Umkreissuche

Durch die Beiden Query Parameter radius und radiusAddress, ist es möglich eine Umgebungssuche zu machen.

Note: Diese beiden Query Parameter werden nur bei den Job Endpunkten unterstützt.

Query Parameter	Erklärung
`radius`	Maximale Entfernung in Metern
`radiusAddress`	Startpunkt der Umkreissuche. Eine URL Encoded Adresse, welche durch Google Maps gefunden werden kann

Note: Die Adressen müssen zuerst in Längen und Breitengrade aufgelöst werden, weshalb die erste Anfrage mit einer neuen Adresse etwas länger braucht (1-2 Sekunden). Danach wird die Adresse bis zum nächsten Server Neustart gecached.

Wenn einer der beiden Query Parameter nicht angegeben wird oder die Adresse invalid ist, wird keine Umgebungssuche durchgeführt und die beiden Parameter werden ignoriert.

Beispiel:

https://api.schuelerkarriere.de/jobs?status=publish&radius=50000&radiusAddress=Ellernstra%C3%9Fe%2025%2C%2030175%20Hannover

==> Gibt alle Job Posts zurück, welche eine Maximal Entfernung von 50km zur Ellernstraße 25 in Hannover haben.

Fehler:

Auch Fehler werden als JSON zurückgegeben. Die Fehler Objekt Struktur:

{
  "error": "Internal Server Error",
  "message": "Some kind of message",
  "statusCode": 500
}

Sorting

Um die Ergebnisse eine Anfrage zu sortieren, können sie einfach den Query Parameter sortBy nutzen. Standardmäßig wird absteigend sortiert. Um das zu ändern, können sie den Parameter descending auf false setzen. Der Wert des sortBy Parameters ist die zu benutzende Eigenschaft.

Ein Beispiel:

Sie möchten die 10 neusten Jobs aufrufen:

https://api.schuelerkarriere.de/jobs?sortBy=date&limit=10

Sie möchten die 10 ältesten Jobs aufrufen:

https://api.schuelerkarriere.de/jobs?sortBy=date&limit=10&descending=false

JSON oder XML

Die API unterstützt beide Formate. Standardmäßig wird JSON benutzt. Um dies zu ändern, setzen sie einfach den Query Parameter xml auf true.

Beispiel:

https://api.schuelerkarriere.de/jobs?sortBy=date&limit=10&descending=false&xml=true

NOTE: Wenn ein Fehler auftritt, wird dieser immer in JSON zurückgegeben. Mehr zu Fehlern.

Endpunkte

Firmen:

Endpunkt:
/companies + Filter

JSON Struktur:

Eine Array mit Objekten, welche folgende Struktur haben:

{
    "name": "Vodafone", // Name der Firma (Required)
    "id": "449", // ID (Required)
    "logo": "https://www.schuelerkarriere.de/wp-content/uploads/wp-jobhunt-users/04_Symbol-im-Bild-5-270x203.jpg", // Link zum Logo (Required)
    "url": "https://www.schuelerkarriere.de/employer/vodafone", // Link zum Profil der Firma (Required)
    "facebook": "", // Facebook Link
    "twitter": "", // Twitter Link
    "linkedIn": "", // LinkedIn Link
    "website": "https://www.vodafone.de/", // Webseite
    "googlePlus": "", // GooglePlus Link
    "phoneNumber": "", // Telefon Nummer. Es gibt kein festes Format.
    "address": "Ferdinand-Braun-Platz 1\r\n40549 Düsseldorf\r\nDeutschland",
    "description": "<p>Wir sind Teil der ...", // Beschreibung zur Firma. Muss nicht zwingend HTML sein
    "longitude": 6.731900215148926,
    "latitude": 51.23513412475586,
    "country": "deutschland", 
    "city": "duesseldorf",
    "nicename": "vodafone" // (Required)
}

Jobs/Anzeigen

Endpunkt:
/jobs + Filter

JSON Struktur:

Eine Array mit Objekten, welche folgende Struktur haben:

{
    "id": "20252", // (Required)
    "title": "Duales oder ausbildungsintegriertes Studium Wirtschaftsinformatik", // (Required)
    "company": { ... }, // Firmen Struktur
    "date": "2018-10-24T11:45:04.000Z", // (Required)
    "country": "deutschland",
    "city": "hamburg",
    "qualification": [ // Eine Array mit qualificationen
        "gymnasium",
          "fachhochschulreife"
    ],
    "sector": {
        "slug": "auto-transport-verkehr",
        "name": "Auto, Verkehr, Transport, Lager"
    },
    "careerlevel": {
          "slug": "student",
          "name": "Student"
    },
    "address": "Taunusanlage 12 \r\n60325 Frankfurt am Main\r\nDeutschland",
    "url": "https://schuelerkarriere.de/jobs/duales-oder-ausbildungsintegriertes-studium-wirtschaftsinformatik", // (Required)
    "content": "<p class=\"bodytext\">Damit ...", // Muss kein html sein (Required)
    "description": "Keine Beschreibung.", // Muss kein html sein (Required)
    "gender": "both", // both, male, female
    "views": 59,
    "status": "publish", // draft, publish, trash
    "latitude": 50.11381530761719,
    "longitude": 8.668187141418457,
    "premium": true // Zeigt an, ob es eine Premium oder normale Anzeige ist.
}

Sektoren

Endpunkt:
/sectors

JSON Struktur:

Eine Array mit Slugs:

[
      {
        "slug": "medien-druck",
        "name": "Medien, Druck"
      },
      {
        "slug": "umwelt-biologie-chemie-physik",
        "name": "Umwelt, Labor"
      },
      // ...
  ]

Careerlevels

Endpunkt:
/careerlevels

JSON Struktur:

Eine Array mit Slugs:

[
      {
        "slug": "azubi",
        "name": "Azubi"
      },
      {
        "slug": "student",
        "name": "Student"
      },
      // ...
  ]