SA server support

Author: man90es

README.md

@@ -1,13 +1,13 @@
 # BDO-REST-API
-A collector for Black Desert Online player in-game data that provides an unofficial REST API.
+A collector for Black Desert Online player in-game data that provides an unofficial REST API. It currently supports European, North American and South American servers. (Korean server support will be added in the future).
 
 ## Projects using this API
 - [BDO Leaderboards](https://bdo.hemlo.cc/leaderboards/) ([GitHub](https://github.com/octoman90/BDO-Leaderboards)): web-based leaderboards for Black Desert Online.
 
 ## How to start using it
 There are two ways to use this API in your apps:
-1. https://bdo-rest-api.herokuapp.com/v1 is an instance that I host. Keep in mind that it may be slow to respond, and might just stop working one day. It's also rolling-release: if the API changes in the master branch on GitHub, this instance will reflect it immediately and your app may break. The API documentation can be viewed [here](https://gitlab.com/man90/black-desert-social-rest-api/-/tree/master/doc/api/openapi.json).
-2. Host it yourself. The server may cost some money, but the process is trivial. This approach will give you more stability and freedom. There are four easy steps to it:
+* https://bdo-rest-api.herokuapp.com/v1 is an instance that I host. Be aware that if the API changes in the master branch on GitHub, this instance will reflect it immediately and your app may break. The API documentation can be viewed [here](https://gitlab.com/man90/black-desert-social-rest-api/-/tree/master/doc/api/openapi.json).
+* Host it yourself. Renting a VPS may cost some money, but the process is trivial. This approach will give you more stability and freedom. There are four easy steps to it:
 	1. Build the server from the source code following [this guide](doc/buildingFromSource.md) or download a prebuilt Linux binary from [here](https://gitlab.com/man90/black-desert-social-rest-api/-/pipelines).
 	2. Set the environment variables if you want. The list is in a section below.
 	3. Run the binary. Possible flags are described in a section below.

doc/api/openapi.json

@@ -17,10 +17,10 @@
 			"region": {
 				"name": "region",
 				"in": "query",
-				"description": "Only Eropean and North American servers are supported. If you omit this parameter, it's assumed that you want to search on the European server.",
+				"description": "Only Eropean, North American and South American servers are supported. If you omit this parameter, it's assumed that you want to search on the European server.",
 				"schema": {
 					"type": "string",
-					"enum": ["EU", "NA"],
+					"enum": ["EU", "NA", "SA"],
 					"example": "EU"
 				}
 			}
@@ -52,6 +52,16 @@
 						"schema": {
 							"type": "string"
 						}
+					},
+					{
+						"name": "region",
+						"in": "query",
+						"description": "Only Eropean, North American and South American servers are supported. You may omit this parameter for the European and North American servers.",
+						"schema": {
+							"type": "string",
+							"enum": ["EU", "NA", "SA"],
+							"example": "EU"
+						}
 					}
 				],
 				"responses": {
@@ -262,6 +272,10 @@
 															"type": "string",
 															"example": "Ninja"
 														},
+														"main": {
+															"type": "boolean",
+															"example": true
+														},
 														"level": {
 															"type": "number",
 															"example": 56

handlers/GetAdventurer.go

@@ -13,15 +13,23 @@ func GetAdventurer(w http.ResponseWriter, r *http.Request) {
 	setHeaders(w)
 
 	profileTargetParams, profileTargetProvided := r.URL.Query()["profileTarget"]
+	regionParams, regionProvided := r.URL.Query()["region"]
 
 	// Return status 400 if a required parameter is invalid
 	if !profileTargetProvided || !validators.ValidateProfileTarget(&profileTargetParams[0]) {
 		w.WriteHeader(http.StatusBadRequest)
 		return
 	}
 
+	// Set defaults for optional parameters
+	region := defaultRegion
+
+	if regionProvided && validators.ValidateRegion(&regionParams[0]) {
+		region = regionParams[0]
+	}
+
 	// Run the scraper
-	if data, status := scrapers.ScrapeAdventurer(url.QueryEscape(profileTargetParams[0])); status == http.StatusOK {
+	if data, status := scrapers.ScrapeAdventurer(region, url.QueryEscape(profileTargetParams[0])); status == http.StatusOK {
 		json.NewEncoder(w).Encode(data)
 	} else {
 		w.WriteHeader(status)

scrapers/ScrapeAdventurer.go

@@ -11,12 +11,14 @@ import (
 	"github.com/gocolly/colly/v2"
 
 	"bdo-rest-api/models"
+	"bdo-rest-api/translators"
 )
 
-func ScrapeAdventurer(profileTarget string) (profile models.Profile, status int) {
+func ScrapeAdventurer(region string, profileTarget string) (profile models.Profile, status int) {
 	c := collyFactory()
 
 	profile.ProfileTarget = profileTarget
+	profile.Region = region
 	status = http.StatusNotFound
 
 	c.OnHTML(closetimeSelector, func(e *colly.HTMLElement) {
@@ -63,6 +65,10 @@ func ScrapeAdventurer(profileTarget string) (profile models.Profile, status int)
 			Class: e.ChildText(".character_info .character_symbol em:last-child"),
 		}
 
+		if region == "SA" {
+			translators.TranslateClassName(&character.Class)
+		}
+
 		e.ForEach(`.selected_label`, func(ind int, el *colly.HTMLElement) {
 			character.Main = true
 		})
@@ -88,9 +94,13 @@ func ScrapeAdventurer(profileTarget string) (profile models.Profile, status int)
 			e.ForEach(".character_spec:not(.lock) .spec_level", func(ind int, el *colly.HTMLElement) {
 				// "Beginner1" → "Beginner 1"
 				i := regexp.MustCompile(`[0-9]`).FindStringIndex(el.Text)[0]
-				level := el.Text[:i] + " " + el.Text[i:]
+				wordLevel := el.Text[:i]
+
+				if region == "SA" {
+					translators.TranslateSpecLevel(&wordLevel)
+				}
 
-				specLevels[ind] = level
+				specLevels[ind] = wordLevel + " " + el.Text[i:]
 			})
 
 			if len(specLevels[0]) > 0 {
@@ -117,7 +127,7 @@ func ScrapeAdventurer(profileTarget string) (profile models.Profile, status int)
 		profile.Privacy = profile.Privacy | models.PrivateSpecs
 	})
 
-	c.Visit(fmt.Sprintf("https://www.naeu.playblackdesert.com/en-US/Adventure/Profile?profileTarget=%v", profileTarget))
+	c.Visit(fmt.Sprintf("%v/Adventure/Profile?profileTarget=%v", getSiteRoot(region), profileTarget))
 
 	return
 }

scrapers/ScrapeAdventurerSearch.go

@@ -8,9 +8,10 @@ import (
 	"github.com/gocolly/colly/v2"
 
 	"bdo-rest-api/models"
+	"bdo-rest-api/translators"
 )
 
-func ScrapeAdventurerSearch(region, query string, searchType uint8, page uint16) (profiles []models.Profile, status int) {
+func ScrapeAdventurerSearch(region string, query string, searchType uint8, page uint16) (profiles []models.Profile, status int) {
 	c := collyFactory()
 	closetime := false
 
@@ -20,20 +21,29 @@ func ScrapeAdventurerSearch(region, query string, searchType uint8, page uint16)
 
 	c.OnHTML(`.box_list_area li:not(.no_result)`, func(e *colly.HTMLElement) {
 		profile := models.Profile{
-			Region:        e.ChildText(".region_info"),
+			Region:        region,
 			FamilyName:    e.ChildText(".title a"),
 			ProfileTarget: extractProfileTarget(e.ChildAttr(".title a", "href")),
 			Characters:    make([]models.Character, 1),
 		}
 
-		if e.ChildAttr(".state a", "href") != "javscript:void(0)" {
+		if region != "SA" {
+			profile.Region = e.ChildText(".region_info")
+		}
+
+		if len(e.ChildAttr(".state a", "href")) > 0 {
 			profile.Guild = &models.GuildProfile{
 				Name: e.ChildText(".state a"),
 			}
 		}
 
-		profile.Characters[0].Name = e.ChildText(".text")
 		profile.Characters[0].Class = e.ChildText(".name")
+		profile.Characters[0].Main = true
+		profile.Characters[0].Name = e.ChildText(".text")
+
+		if region == "SA" {
+			translators.TranslateClassName(&profile.Characters[0].Class)
+		}
 
 		if level, err := strconv.Atoi(e.ChildText(".level")[3:]); err == nil {
 			profile.Characters[0].Level = uint8(level)
@@ -42,7 +52,7 @@ func ScrapeAdventurerSearch(region, query string, searchType uint8, page uint16)
 		profiles = append(profiles, profile)
 	})
 
-	c.Visit(fmt.Sprintf("https://www.naeu.playblackdesert.com/en-US/Adventure?region=%v&searchType=%v&searchKeyword=%v&Page=%v", region, searchType, query, page))
+	c.Visit(fmt.Sprintf("%v/Adventure?region=%v&searchType=%v&searchKeyword=%v&Page=%v", getSiteRoot(region), region, searchType, query, page))
 
 	if closetime {
 		status = http.StatusServiceUnavailable

scrapers/ScrapeGuild.go

@@ -48,7 +48,7 @@ func ScrapeGuild(region, name string) (guildProfile models.GuildProfile, status
 
 	c.OnHTML(`.line_list:not(.mob_none) li:last-child .desc`, func(e *colly.HTMLElement) {
 		text := dry(e.Text)
-		if text != "None" {
+		if text != "None" && text != "N/A" {
 			guildProfile.Occupying = text
 		}
 	})
@@ -62,7 +62,7 @@ func ScrapeGuild(region, name string) (guildProfile models.GuildProfile, status
 		guildProfile.Members = append(guildProfile.Members, member)
 	})
 
-	c.Visit(fmt.Sprintf("https://www.naeu.playblackdesert.com/en-US/Adventure/Guild/GuildProfile?guildName=%v&region=%v", name, region))
+	c.Visit(fmt.Sprintf("%v/Adventure/Guild/GuildProfile?guildName=%v&region=%v", getSiteRoot(region), name, region))
 
 	return
 }

scrapers/ScrapeGuildSearch.go

@@ -9,6 +9,7 @@ import (
 	"github.com/gocolly/colly/v2"
 
 	"bdo-rest-api/models"
+	"bdo-rest-api/translators"
 )
 
 func ScrapeGuildSearch(region, query string, page uint16) (guildProfiles []models.GuildProfile, status int) {
@@ -24,7 +25,7 @@ func ScrapeGuildSearch(region, query string, page uint16) (guildProfiles []model
 
 		guildProfile := models.GuildProfile{
 			Name:   e.ChildText(".guild_title a"),
-			Region: e.ChildText(".region_info"),
+			Region: region,
 			Kind:   e.ChildText(".tag_label.guild_label"),
 			Master: &models.Profile{
 				FamilyName:    e.ChildText(".guild_info a"),
@@ -33,6 +34,14 @@ func ScrapeGuildSearch(region, query string, page uint16) (guildProfiles []model
 			CreatedOn: &createdOn,
 		}
 
+		if region != "SA" {
+			guildProfile.Region = e.ChildText(".region_info")
+		}
+
+		if region == "SA" {
+			translators.TranslateGuildKind(&guildProfile.Kind)
+		}
+
 		if membersStr := e.ChildText(".member"); true {
 			population, _ := strconv.Atoi(membersStr)
 			guildProfile.Population = uint8(population)
@@ -41,7 +50,7 @@ func ScrapeGuildSearch(region, query string, page uint16) (guildProfiles []model
 		guildProfiles = append(guildProfiles, guildProfile)
 	})
 
-	c.Visit(fmt.Sprintf("https://www.naeu.playblackdesert.com/en-US/Adventure/Guild?region=%v&page=%v&searchText=%v", region, page, query))
+	c.Visit(fmt.Sprintf("%v/Adventure/Guild?region=%v&page=%v&searchText=%v", getSiteRoot(region), region, page, query))
 
 	if closetime {
 		status = http.StatusServiceUnavailable

scrapers/scraper.go

@@ -30,6 +30,14 @@ func extractProfileTarget(link string) string {
 	return url.QueryEscape(m["profileTarget"][0])
 }
 
+func getSiteRoot(region string) string {
+	if "SA" == region {
+		return "https://www.sa.playblackdesert.com/pt-BR"
+	}
+
+	return "https://www.naeu.playblackdesert.com/en-US"
+}
+
 func collyFactory() (c *colly.Collector) {
 	c = colly.NewCollector()
 	c.SetRequestTimeout(time.Minute / 2)

translators/TranslateClassName.go

@@ -0,0 +1,24 @@
+package translators
+
+var classNameTranslationMap = map[string]string{
+	"Cavaleira Negra": "Dark Knight",
+	"Corsária":        "Corsair",
+	"Domadora":        "Tamer",
+	"Feiticeira":      "Sorceress",
+	"Guardiã":         "Guardian",
+	"Guerreiro":       "Warrior",
+	"Lutador":         "Striker",
+	"Maga":            "Witch",
+	"Mago":            "Wizard",
+	"Mística":         "Mystic",
+	"Musah":           "Musa",
+	"Sábio":           "Sage",
+	"Sagitário":       "Archer",
+	"Valquíria":       "Valkyrie",
+}
+
+func TranslateClassName(className *string) {
+	if val, ok := classNameTranslationMap[*className]; ok {
+		*className = val
+	}
+}

translators/TranslateGuildKind.go

@@ -0,0 +1,12 @@
+package translators
+
+var guildKindTranslationMap = map[string]string{
+	"Clã":    "Clan",
+	"Guilda": "Guild",
+}
+
+func TranslateGuildKind(kind *string) {
+	if val, ok := guildKindTranslationMap[*kind]; ok {
+		*kind = val
+	}
+}