API Dokumentation

Mit Hilfe dieser Dokumentation erfährst du, wie sich Namesia mit einer Vielzahl von Programmiersprachen verwenden lässt.

API-Endpoint

http://api.namesia.de/names/:land/:vornamen

Um vom Server zu erfahren, welches Geschlecht ein Vorname hat, musst du lediglich das Land :land sowie den jeweiligen Vornamen :vornamen in einem GET-Request übergeben. Dabei werden die Parameter unproblematisch mit der URL übergeben. Zur Sicherheit müssen die Parameter jedoch URL-encodiert werden!

Antwort des Servers

{"name":"Max", "gender":"male", "country":"de"}

Nachdem du die Anfrage abgesendet hast, erhältst du, wenn alles fehlerlos verlaufen ist, vom Server eine Antwort im JSON-Format. Besagte Antwort beinhaltet dabei die Felder name, gender und country. Nun kannst du das Ergebnis in deiner Anwendung einsetzen. Ist der Name unbekannt, antwortet der Server mit einer leeren Liste.

Curl

Jeder kennt es, jeder nutzt es. cURL ist wohl das bekannteste Tool, um schnell eine API zu testen. Einfach die komplette URL eingeben, fertig.

$ curl http://api.namesia.de/names/de/maximilian
> GET /names/de/maximilian HTTP/1.1
> Host: api.namesia.de
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Sat, 23 Nov 2013 17:32:16 GMT
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Content-Length: 50
< Cache-Control: max-age=0
< Expires: Sat, 23 Nov 2013 17:32:16 GMT
< X-UA-Compatible: IE=edge,chrome=1
< Connection: Keep-Alive, close
$ {"name":"Maximilian","gender":"male","country":"de"}

Ruby

Zur Sicherheit solltest du den Namen mit Hilfe von URI.escape »URL-encoden«. So werden auch Umlaute etc. richtig übertragen.

require 'json'
require 'open-uri'
require 'uri'

first_name = URI.escape('maximilian')
country    = 'de'
full_url   = "http://api.namesia.de/names/#{country}/#{first_name}"

response   = open(full_url)
name_hash  = JSON.load(response)

puts "Geschlecht: #{name_hash['gender']}"

Python

Wie auch bei Ruby sollte der Name vor dem API-Aufruf zunächst mit Hilfe der »urllib« URL-encoded werden.

import json
import httplib
import urllib

first_name = urllib.quote_plus("maximilian")
country    = "de"
req_path   = "/names/{c}/{fn}".format(c=country, fn=first_name)

connection = httplib.HTTPConnection("api.namesia.de")
connection.request("GET", req_path)

response   = connection.getresponse()
name_dict  = json.loads(response.read())

print "Geschlecht: %s" % name_dict["gender"]

PHP

URL-encoden kann PHP ohne externe Bibliothek. Somit kannst du schnell abfragen, welches Geschlecht zu einem Namen passt.

$firstName  = urlencode("maximilian");
$country    = "de";
$full_url   = "http://api.namesia.de/names/{$country}/{$firstName}";

$response   = file_get_contents($full_url);
$name_obj   = json_decode($response);

echo "Geschlecht: {$name_obj->gender}";

Node.js

JavaScript führt das URL-encoden leider nicht so durch wie gedacht. Deshalb müssen die »%20« erst mit »+« ersetzt werden.

var http = require('http');

var firstName = encodeURIComponent("maximilian").replace(/%20/g, "+");
var country   = "de";
var full_url  = "http://api.namesia.de/names/"+country+"/"+firstName;

var req = http.get(full_url, function(response) {
    var data = '';

    response.on('data', function (chunk){
        data += chunk;
    });

    response.on('end',function(){
        var nameObj = JSON.parse(data);
        console.log("Geschlecht: " + nameObj.gender);
    });

});