GBIF occurrence API: lọc uncertainty, basisOfRecord, license
GBIF occurrence API là endpoint tìm kiếm bản ghi xuất hiện của sinh vật trong mạng GBIF, mỗi bản ghi là một lần ghi nhận loài tại một nơi, một lúc, từ một bộ dữ liệu cụ thể. Bài này viết cho người dựng bảng phân bố loài, hay nhầm mỗi điểm trên bản đồ là một cá thể và quên rằng tọa độ có độ bất định. ProxyVN gọi API thật ngày 05/11/2026 cho loài sẻ nhà châu Á tại Việt Nam, dựng bảng lọc chất lượng từng bước và ghi giấy phép theo từng bản ghi.
GBIF occurrence API: mục tiêu và phạm vi không lặp
Phần này chốt bài toán, đầu ra và ranh giới với bài iNaturalist.
Bài toán cần giải
Một nhóm nghiên cứu muốn vẽ bản đồ nơi loài Passer montanus được ghi nhận ở Việt Nam. Họ tải các điểm từ GBIF, đếm điểm theo tỉnh và báo cáo số lượng. Người phản biện hỏi: điểm nào chính xác tới vài mét, điểm nào lệch hàng chục km, và vì sao gần chín phần mười điểm đến từ một bộ dữ liệu chim.
Đầu ra nghiệm thu
Đầu ra là dataset occurrence với key, taxonKey, scientificName, basisOfRecord, occurrenceStatus, individualCount, eventDate, tọa độ, coordinateUncertaintyInMeters, issues, license, datasetKey, publishingOrgKey. Đi kèm là bảng lọc chất lượng, mỗi bước ghi số bản ghi còn lại và lý do loại.
Ranh giới với bài iNaturalist
Bài iNaturalist API observations trong cùng cụm đọc bản ghi gốc trên iNaturalist, nơi có geoprivacy và tọa độ bị làm mờ. GBIF là chỉ mục gom từ nhiều nguồn, trong đó có iNaturalist. Bài này nói về basisOfRecord, độ bất định tọa độ, issues và giấy phép trong chỉ mục GBIF. Hai nguồn có thể chứa cùng bản ghi, nên không cộng số đếm của hai bên.
Giới hạn của lab
Lab gọi API thật không cần tài khoản, nghỉ 1,5 giây giữa các lời gọi, tổng dưới mười lời gọi. Lab lấy một trang 300 bản ghi đầu tiên để phân tích chi tiết, cộng các facet trên toàn bộ 11147 bản ghi. Lab không dùng API tải xuống bất đồng bộ cần tài khoản. Kết quả là ảnh chụp chỉ mục ngày 05/11/2026.
Ai nên đọc
Nhà sinh thái học, người làm bảo tồn, sinh viên làm luận văn về phân bố loài. Kỹ sư dữ liệu cần lấy occurrence cho dự án môi trường. Người làm nội dung khoa học cần hiểu đúng một điểm trên bản đồ GBIF nói gì và không nói gì.
Những gì bài không làm
Bài không mô hình hóa phân bố loài, không làm sạch tên khoa học sâu, không dùng API tải xuống lớn. Bài cũng không bàn về loài nhạy cảm mà nguồn đã che tọa độ. Phạm vi là tìm kiếm, đọc và lọc có ghi nhận.
Thuật ngữ dùng trong bài
Occurrence là một bản ghi xuất hiện. Taxon key là ID của một đơn vị phân loại trong cây phân loại của GBIF. BasisOfRecord cho biết bản ghi là quan sát của người, mẫu vật bảo tàng, quan sát bằng máy hay loại khác. CoordinateUncertaintyInMeters là bán kính bất định của tọa độ. Issues là các cờ GBIF gắn khi xử lý bản ghi.
Vì sao chọn loài phổ biến
Lab chọn sẻ nhà châu Á vì đây là loài phổ biến, không nhạy cảm, có nhiều bản ghi từ nhiều nguồn. Loài quý hiếm thường bị nguồn che tọa độ, làm lẫn hai vấn đề: che có chủ đích và độ bất định do đo. Loài phổ biến cho thấy rõ cấu trúc dữ liệu trước.
Thu occurrence GBIF và diễn giải coordinate uncertainty/basisOfRecord với GBIF occurrence API
Phần này đi qua lời gọi đầu và các facet trên toàn bộ kết quả.
Nguồn tài liệu đã đọc
Trang tài liệu Swagger của GBIF chỉ có khung khi tải bằng script, nên brief đọc đặc tả OpenAPI của Occurrence API. Đặc tả liệt kê tham số của /occurrence/search như taxonKey, country, basisOfRecord, hasCoordinate, hasGeospatialIssue, coordinateUncertaintyInMeters, limit, offset, facet. Lab đối chiếu với response thật.
Khớp tên loài trước
Lab gọi /species/match với name là Passer montanus. API trả usageKey 5231198, scientificName Passer montanus (Linnaeus, 1758), rank SPECIES, matchType EXACT, confidence 99, status ACCEPTED. Luôn khớp tên thành key trước, đừng tìm occurrence bằng chuỗi tên.
Đếm bằng limit 0
Gọi /occurrence/search với taxonKey 5231198, country VN, limit 0 và bốn facet. API trả count 11147 mà không trả bản ghi nào. Đây là cách rẻ để biết quy mô trước khi lấy dữ liệu.
Facet basisOfRecord
11066 bản ghi là HUMAN_OBSERVATION, 81 bản ghi là PRESERVED_SPECIMEN. Gần như toàn bộ là quan sát của người. Mẫu vật bảo tàng ít nhưng thường có giá trị lịch sử và có thể kiểm lại. Hai loại có độ tin cậy và ý nghĩa khác nhau, không gộp làm một.
Facet dataset
Một bộ dữ liệu chiếm 9985 bản ghi, là eBird Observation Dataset, loại SAMPLING_EVENT, DOI 10.15468/aomfnb. Bộ iNaturalist research-grade observations có 657 bản ghi. Các bộ khác có 280, 99, 41 bản ghi và ít hơn. Bản đồ của loài này ở Việt Nam chủ yếu phản ánh hoạt động của người quan sát chim dùng eBird.
Facet license
10248 bản ghi CC_BY_4_0, 853 bản ghi CC_BY_NC_4_0, 46 bản ghi CC0_1_0. Giấy phép là thuộc tính của từng bản ghi, đến từ bộ dữ liệu gốc. Dùng lại dữ liệu cho mục đích thương mại phải loại hoặc xin phép với bản ghi NC.
FacetLimit
Lab đặt facetLimit 8, nên facet dataset chỉ trả tám bộ đầu. Tổng của tám bộ có thể nhỏ hơn count. Muốn biết đủ số bộ dữ liệu, tăng facetLimit hoặc phân trang facet. Báo cáo không được viết là chỉ có tám bộ.
Gửi nhiều facet trong một lời gọi
Requests gửi danh sách facet thành nhiều tham số facet lặp lại. API nhận đủ bốn facet trong một lời gọi. Một lời gọi với limit 0 và nhiều facet thay cho nhiều lời gọi đếm riêng.
Ví dụ request bằng Python
import requests, time
s = requests.Session()
s.headers["User-Agent"] = "ProxyVN-docs-lab/1.0 (+https://proxy.vn/)"
B = "https://api.gbif.org/v1"
def get(path, **q):
r = s.get(B + path, params=q, timeout=60)
time.sleep(1.5)
return r.status_code, r.json()
st, m = get("/species/match", name="Passer montanus")
K = m["usageKey"]
st, fac = get("/occurrence/search", taxonKey=K, country="VN", limit=0,
facet=["basisOfRecord", "license", "datasetKey", "occurrenceStatus"], facetLimit=8)
print(fac["count"], [(f["field"], f["counts"][:3]) for f in fac["facets"]])Chọn taxon/country/basisOfRecord từ OpenAPI trong GBIF occurrence API
Bộ lọc nào chạy ở máy chủ, bộ lọc nào chạy ở phía mình, cần rõ ràng.
TaxonKey gồm cả đơn vị con
TaxonKey gồm đơn vị con
Trong 300 bản ghi của trang đầu, taxonKey 5231198 có 296 bản ghi, ba key khác 6090468, 5231199, 5845698 có 2, 1 và 1 bản ghi. Tìm theo taxonKey của loài trả cả bản ghi được định danh tới đơn vị dưới loài. Bảng phải giữ taxonKey của từng bản ghi, không gán cứng key của loài.
Khớp tên có thể ra nhiều kết quả
Matchtype EXACT với confidence 99 là ca dễ. Tên có lỗi chính tả hay tên đồng nghĩa cũ có thể trả FUZZY hoặc trả key của tên chấp nhận khác. Lab kiểm matchType và status trước khi dùng usageKey. Tên trả HIGHERRANK, tức chỉ khớp tới cấp chi, không được dùng làm key loài.
Country là mã ISO hai chữ
Lab dùng country VN. Đây là quốc gia gắn với bản ghi, có thể do nguồn khai báo hoặc GBIF suy ra từ tọa độ. Nếu tọa độ nằm ngoài lãnh thổ khai báo, GBIF gắn issue COUNTRY_COORDINATE_MISMATCH. Lab đưa issue này vào danh sách loại.
OccurrenceStatus
Facet cho thấy cả 11147 bản ghi là PRESENT. Bản ghi ABSENT tồn tại trong một số bộ khảo sát, cho biết đã tìm mà không thấy. Bảng phân bố phải lọc PRESENT, nếu không sẽ vẽ cả điểm vắng mặt như điểm có mặt.
BasisOfRecord lọc ở máy chủ
Tham số basisOfRecord nhận các giá trị như HUMAN_OBSERVATION, PRESERVED_SPECIMEN, MACHINE_OBSERVATION. Nếu nghiên cứu chỉ dùng mẫu vật, lọc ở máy chủ giảm số bản ghi phải tải từ 11147 xuống 81. Lab giữ cả hai loại và lọc ở phía mình để thấy phân bố.
Lọc tọa độ ở máy chủ
Gọi với hasCoordinate true, hasGeospatialIssue false và coordinateUncertaintyInMeters từ 0 tới 1000 trả count 728 trên 11147 bản ghi. Chỉ khoảng 6,5 phần trăm bản ghi qua cả ba điều kiện. Phần lớn bản ghi eBird không có độ bất định đi kèm.
Bảng tham số đã dùng
Tham số |
Giá trị |
Kết quả |
|---|---|---|
species/match name |
Passer montanus |
usageKey 5231198 |
taxonKey + country |
5231198, VN |
11147 |
limit 0 + facet |
4 facet |
Phân bố toàn bộ |
hasCoordinate + hasGeospatialIssue + uncertainty |
true, false, 0,1000 |
728 |
limit |
1000 |
Trả 300 |
offset |
100000 với limit 300 |
400 |
Limit bị cắt im lặng
Gọi với limit 1000, response có limit 300. API không báo lỗi, chỉ trả tối đa 300 bản ghi. Mã phân trang phải đọc limit trong response, không dùng giá trị mình gửi để tính offset trang sau.
Phân trang đúng cách
Mỗi trang tăng offset bằng limit thật trong response, dừng khi endOfRecords là true. Trang đầu của lab có endOfRecords false, offset 0, limit 300. Lấy hết 11147 bản ghi cần khoảng 38 trang. Trong giới hạn của lab, chỉ lấy trang đầu.
Offset có trần
Gọi offset 100000 với limit 300 trả HTTP 400, nội dung văn bản là Max offset of 100001 exceeded: 100000 + 300. Response không phải JSON. Tìm kiếm phân trang chỉ đi được tới khoảng 100000 bản ghi. Lấy nhiều hơn phải dùng API tải xuống có tài khoản.
Đọc occurrence key cùng coordinate uncertainty trong GBIF occurrence API
Phần này đọc trang 300 bản ghi đầu và các trường chính.
Trường của một bản ghi
Độ bất định tọa độ
Mỗi bản ghi có key, datasetKey, publishingOrgKey, basisOfRecord, occurrenceStatus, taxonKey, acceptedTaxonKey, scientificName, decimalLatitude, decimalLongitude, coordinateUncertaintyInMeters, eventDate, issues, license và nhiều trường Darwin Core khác. Key là ID ổn định của bản ghi trong chỉ mục GBIF.
Độ bất định trong 300 bản ghi
88 bản ghi không có coordinateUncertaintyInMeters. 139 bản ghi có độ bất định từ 1000 m trở xuống. 73 bản ghi có độ bất định trên 1000 m, lớn nhất là 31169 m. Một điểm có độ bất định 31 km có thể nằm ở bất kỳ đâu trong vòng tròn bán kính 31 km quanh tọa độ hiển thị.
Thiếu độ bất định không có nghĩa là chính xác
88 bản ghi không có trường này. Có thể nguồn không ghi, có thể tọa độ được lấy từ tên địa danh. Lab xếp chúng vào nhóm không biết độ chính xác. Coi chúng là chính xác tới mét là sai.
Độ bất định cỡ ba mươi km
Giá trị lớn nhất 31169 m cùng cỡ với độ chính xác công khai khoảng 30 km của bản ghi bị làm mờ trên iNaturalist ở bài kế tiếp. Lab chưa nối từng bản ghi giữa hai nguồn để khẳng định. Điểm cần nhớ là độ bất định lớn có thể do nguồn cố ý làm mờ, không do lỗi đo.
EventDate có nhiều dạng
EventDate có thể là một ngày, một khoảng ngày hay chỉ năm. Bảng giữ chuỗi gốc và thêm cột năm khi cần thống kê theo năm. Không ép mọi giá trị thành một ngày cụ thể, vì khoảng ngày là thông tin thật của bản ghi.
IndividualCount thường trống
261 trên 300 bản ghi không có individualCount. 20 bản ghi ghi 1, các giá trị 2, 3, 5 xuất hiện vài lần. Một bản ghi không phải một cá thể. Một bản ghi có thể là một đàn, có thể là một lần nghe tiếng. Đếm bản ghi là đếm lần ghi nhận.
Tọa độ thập phân và datum
Tọa độ trả dưới dạng decimalLatitude và decimalLongitude, hệ WGS84 sau xử lý. Issue GEODETIC_DATUM_ASSUMED_WGS84 ở 2 bản ghi cho biết nguồn không khai báo datum và GBIF giả định WGS84. Với bản đồ tỉ lệ nhỏ, sai khác này không đáng kể, nhưng vẫn ghi lại.
Issues
Bốn issue phổ biến nhất là CONTINENT_DERIVED_FROM_COORDINATES 262, COORDINATE_ROUNDED 259, TAXON_ID_NOT_FOUND 189, GEODETIC_DATUM_ASSUMED_WGS84 2. Phần lớn issue là thông tin xử lý, không phải lỗi nghiêm trọng. COORDINATE_ROUNDED cho biết tọa độ đã bị làm tròn khi xử lý.
TAXON_ID_NOT_FOUND không phải tên sai
189 bản ghi có TAXON_ID_NOT_FOUND. Bản ghi vẫn khớp được loài qua tên khoa học. Issue này thường cho biết ID phân loại gốc của nguồn không tìm được trong hệ GBIF. Lab không loại các bản ghi này, vì taxonKey đã được gán.
License dạng URL trong bản ghi
Facet trả license dạng CC_BY_4_0, còn bản ghi trả dạng URL như http://creativecommons.org/licenses/by/4.0/legalcode. Hai dạng khác nhau cho cùng giấy phép. Bảng chuẩn hóa về một dạng trước khi so, nếu không lọc theo giấy phép sẽ trượt.
Mã đọc bản ghi
st, d = get("/occurrence/search", taxonKey=K, country="VN", limit=300)
rows = [dict(key=x["key"], taxonKey=x.get("taxonKey"), basisOfRecord=x.get("basisOfRecord"),
occurrenceStatus=x.get("occurrenceStatus"), individualCount=x.get("individualCount"),
lat=x.get("decimalLatitude"), lon=x.get("decimalLongitude"),
unc=x.get("coordinateUncertaintyInMeters"), issues="|".join(x.get("issues", [])),
license=x.get("license"), datasetKey=x.get("datasetKey")) for x in d["results"]]Lọc chất lượng theo tiêu chí có ghi nhận với GBIF occurrence API
Mỗi bước lọc ghi số còn lại, để người đọc biết dữ liệu cuối từ đâu ra.
Các bước lọc
Bảng lọc chất lượng
Lab áp bảy bước theo thứ tự: tất cả, có tọa độ, PRESENT, basisOfRecord thuộc nhóm quan sát hoặc mẫu vật, có độ bất định, độ bất định từ 1000 m trở xuống, không có issue tọa độ nghiêm trọng. Danh sách issue nghiêm trọng gồm ZERO_COORDINATE, COORDINATE_INVALID, COUNTRY_COORDINATE_MISMATCH, COORDINATE_OUT_OF_RANGE, PRESUMED_SWAPPED_COORDINATE.
Vì sao không loại theo COORDINATE_ROUNDED
259 bản ghi có COORDINATE_ROUNDED. Nếu coi mọi issue là lỗi, gần như cả trang bị loại. Làm tròn tọa độ thường chỉ ở vài chữ số thập phân cuối, không đổi kết luận ở tỉ lệ bản đồ thông thường. Lab chỉ loại theo danh sách issue nghiêm trọng đã ghi rõ.
Kết quả từng bước
Từ 300 bản ghi, bốn bước đầu giữ nguyên 300. Bước có độ bất định còn 212. Bước độ bất định từ 1000 m trở xuống còn 139. Bước issue nghiêm trọng vẫn 139. Bước loại nhiều nhất là độ bất định, không phải issue.
Bảng lọc chất lượng
Bước |
Điều kiện |
Còn lại |
|---|---|---|
1 |
Tất cả |
300 |
2 |
Có tọa độ |
300 |
3 |
occurrenceStatus PRESENT |
300 |
4 |
basisOfRecord quan sát hoặc mẫu vật |
300 |
5 |
Có coordinateUncertaintyInMeters |
212 |
6 |
Độ bất định từ 1000 m trở xuống |
139 |
7 |
Không issue tọa độ nghiêm trọng |
139 |
Thứ tự bước quan trọng cho báo cáo
Kết quả cuối không đổi khi đảo thứ tự lọc, nhưng số loại ở từng bước thì đổi. Đặt các bước ít gây tranh cãi trước, như có tọa độ và PRESENT, rồi mới tới ngưỡng tùy chọn như độ bất định. Người đọc thấy rõ phần lớn dữ liệu bị loại vì lựa chọn của mình hay vì lỗi dữ liệu.
Ngưỡng 1000 m là lựa chọn của mình
Ngưỡng 1000 m hợp cho bản đồ cấp xã hay khu bảo tồn nhỏ. Bản đồ cấp tỉnh có thể chấp nhận 10 km. Ngưỡng là quyết định của nghiên cứu, ghi rõ trong phương pháp. GBIF không đặt ngưỡng nào là đúng.
Trang đầu không đại diện
Trang 300 bản ghi đầu có 189 bản ghi iNaturalist và 111 bản ghi không có datasetName, giấy phép CC BY-NC chiếm 186. Trong khi đó trên toàn bộ 11147 bản ghi, eBird chiếm 9985 và CC BY chiếm 10248. Thứ tự mặc định của API không phải mẫu ngẫu nhiên. Đừng suy tỉ lệ toàn bộ từ trang đầu.
Lọc ở máy chủ cho số toàn bộ
Để biết toàn bộ còn bao nhiêu sau lọc, dùng tham số ở máy chủ với limit 0 như lời gọi trả 728. Lọc ở phía mình chỉ dùng cho trang đã tải để hiểu cơ chế. Hai con số phải ghi rõ nguồn trong báo cáo.
Lưu cả bản ghi bị loại
Bản ghi bị loại không xóa. Thêm cột loai_o_buoc ghi tên bước loại. Phản biện hỏi vì sao một điểm biến mất, bảng trả lời ngay. Khi đổi ngưỡng, chạy lại trên cùng bảng mà không cần gọi API.
Mã lọc có ghi nhận
SEVERE = ["ZERO_COORDINATE", "COORDINATE_INVALID", "COUNTRY_COORDINATE_MISMATCH",
"COORDINATE_OUT_OF_RANGE", "PRESUMED_SWAPPED_COORDINATE"]
steps = [("co toa do", lambda r: r["lat"] is not None),
("PRESENT", lambda r: r["occurrenceStatus"] == "PRESENT"),
("co uncertainty", lambda r: r["unc"] is not None),
("uncertainty<=1000", lambda r: r["unc"] is not None and r["unc"] <= 1000),
("khong issue nghiem trong", lambda r: not any(i in r["issues"] for i in SEVERE))]
cur = rows; log = [("tat ca", len(cur))]
for name, f in steps:
cur = [r for r in cur if f(r)]
log.append((name, len(cur)))Đối soát license và nguồn dataset, không đồng nhất count với cá thể trong GBIF occurrence API
Phần này nói về giấy phép, nguồn và cách diễn giải số đếm.
Giấy phép không đổi theo lọc chất lượng
Lọc chất lượng làm tỉ lệ giấy phép thay đổi. Trong 88 bản ghi thiếu độ bất định có 73 bản ghi không thuộc iNaturalist, 76 bản ghi mang CC BY. Trong 212 bản ghi có độ bất định có 174 bản ghi iNaturalist, cũng 174 bản ghi mang CC BY-NC. Đây là hệ quả của nguồn dữ liệu, không phải do giấy phép ảnh hưởng chất lượng. Báo cáo nên ghi phân bố giấy phép ở cả hai thời điểm.
Giấy phép sau lọc
139 bản ghi còn lại có 108 CC BY-NC 4.0, 27 CC BY 4.0, 4 CC0. Nếu sản phẩm cuối là thương mại, chỉ 31 bản ghi dùng không cần xin phép thêm. Lọc chất lượng và lọc giấy phép là hai bước độc lập, cả hai cần ghi vào bảng.
Trích dẫn bộ dữ liệu
Mỗi bản ghi có datasetKey. Trích dẫn đúng là trích dẫn các bộ dữ liệu gốc, hoặc dùng DOI của một lần tải xuống qua API tải có tài khoản. Lab gọi /dataset/4fa7b334... và thấy bộ eBird có DOI 10.15468/aomfnb. Bảng giữ datasetKey để dựng danh sách trích dẫn.
Cùng bản ghi ở hai nguồn
Bộ iNaturalist research-grade có 657 bản ghi cho loài này tại Việt Nam trong GBIF. Nếu nghiên cứu lấy thêm dữ liệu thẳng từ iNaturalist rồi cộng với GBIF, 657 bản ghi đó có thể bị đếm hai lần. Không gộp số đếm vô điều kiện. Khi gộp, khóa theo catalogNumber hoặc ID gốc của iNaturalist.
Sampling event và checklist
Bộ eBird có loại SAMPLING_EVENT. Mỗi bản ghi là một loài trong một checklist của một lần quan sát. Checklist cho biết nỗ lực quan sát, thông tin rất có ích cho mô hình phân bố. Occurrence search chỉ trả bản ghi loài, không trả checklist đầy đủ, nên muốn dùng nỗ lực phải lấy từ nguồn eBird.
Count không phải số cá thể
11147 là số bản ghi. Một người quan sát chim có thể gửi nhiều checklist ở cùng địa điểm trong một mùa, mỗi checklist một bản ghi. Báo cáo viết đúng là 11147 lần ghi nhận, không viết 11147 con sẻ.
Thiên lệch người quan sát
Bản ghi eBird tập trung ở nơi người quan sát chim hay đến. Bản đồ dày đặc ở một khu không có nghĩa loài đông hơn ở đó. Phân tích phân bố cần mô hình hóa nỗ lực quan sát, nằm ngoài phạm vi bài, nhưng báo cáo phải nhắc thiên lệch này.
Nhà xuất bản dữ liệu
PublishingOrgKey cho biết tổ chức xuất bản bộ dữ liệu lên GBIF. Một tổ chức có thể xuất bản nhiều bộ. Danh sách cảm ơn trong báo cáo nên nêu cả bộ dữ liệu và tổ chức xuất bản.
Bảng nguồn và giấy phép
Nguồn |
Bản ghi toàn bộ |
Ghi chú |
|---|---|---|
eBird Observation Dataset |
9985 |
SAMPLING_EVENT, DOI 10.15468/aomfnb |
iNaturalist research-grade |
657 |
Có thể trùng với dữ liệu lấy thẳng từ iNaturalist |
Các bộ khác |
khoảng 505 |
280, 99, 41 và nhỏ hơn |
CC BY 4.0 |
10248 |
Ghi nguồn |
CC BY-NC 4.0 |
853 |
Không thương mại |
CC0 |
46 |
Không bắt buộc ghi nguồn |
Đầu ra nghiệm thu: Dataset occurrence key taxon license uncertainty và bảng lọc chất lượng của GBIF occurrence API
Phần này liệt kê điều kiện để coi dataset là xong.
Tệp occ.csv
Mỗi bản ghi một dòng với key, taxonKey, acceptedTaxonKey, scientificName, basisOfRecord, occurrenceStatus, individualCount, eventDate, lat, lon, coordinateUncertaintyInMeters, issues, license, datasetKey, publishingOrgKey, datasetName, catalogNumber, gbifID. Lab ghi 300 dòng.
Bảng lọc
Bảng bảy bước với số còn lại ở mỗi bước, cộng ngưỡng đã dùng. Lab có 300, 300, 300, 300, 212, 139, 139.
Bảng giấy phép
Phân bố giấy phép trước và sau lọc, chuẩn hóa về một dạng mã.
Kiểm khóa
Không có hai dòng cùng key trong occ.csv. Mỗi dòng có datasetKey và license. Lab kiểm trên 300 dòng.
Bảng nghiệm thu của lab
Nghiệm thu dữ liệu loài
Hạng mục |
Kết quả 05/11/2026 |
|---|---|
usageKey Passer montanus |
5231198 |
Bản ghi tại VN |
11147 |
eBird trên toàn bộ |
9985 |
Trang đầu có độ bất định từ 1 km trở xuống |
139 trên 300 |
Lọc máy chủ cùng điều kiện |
728 trên 11147 |
limit 1000 |
Trả 300 |
offset 100000 |
400 văn bản |
Những gì lab chưa chạy
Lab chưa dùng API tải xuống có DOI, chưa lấy hết 11147 bản ghi, chưa thử loài nhạy cảm, chưa nối bản ghi GBIF với bản ghi iNaturalist theo ID. Lab cũng chưa thử facet theo năm hay theo tỉnh.
Vận hành GBIF occurrence API trong pipeline dữ liệu loài
Chỉ mục GBIF được cập nhật liên tục, pipeline cần ghi rõ thời điểm.
Tìm kiếm cho khám phá, tải xuống cho nghiên cứu
Tìm kiếm phân trang hợp cho khám phá và mẫu nhỏ. Nghiên cứu công bố nên dùng API tải xuống có DOI, vì DOI cho phép người khác lấy lại đúng tập dữ liệu. Tìm kiếm có trần offset 100000, tải xuống không bị trần đó.
Lịch cập nhật
Bộ dữ liệu gốc được GBIF nạp lại theo chu kỳ riêng. Số đếm của cùng truy vấn có thể đổi giữa hai tuần. Ghi count và ngày gọi cùng mỗi lần lấy.
Lưu đặc tả OpenAPI
Đặc tả occurrence.json có thể đổi theo phiên bản API. Lưu bản đã đọc cùng dự án, ghi ngày tải. Khi một tham số bỗng không còn hiệu lực, so với bản đã lưu để biết thay đổi ở đâu.
Nhịp gọi
Lab nghỉ 1,5 giây giữa các lời gọi. Với vài nghìn bản ghi, phân trang 300 mỗi lượt cần vài chục lời gọi. Không gọi song song. Dữ liệu lớn hơn thì chuyển sang tải xuống.
Bản đặc tả lab đã lưu
Lab tải occurrence.json ngày 05/11/2026, HTTP 200, 225336 byte, lưu cùng thư mục lab. Khi đọc lại bài sau vài tháng, so bản này với bản mới để biết tham số nào đã thêm hay đổi tên.
Xử lý lỗi
400 với offset là trần phân trang, đổi cách lấy. Response 400 là văn bản, không gọi json trước khi kiểm. 5xx và lỗi mạng thử lại có giãn cách. 200 với limit nhỏ hơn mức gửi không phải lỗi, chỉnh offset theo limit trả về.
Proxy ở tầng mạng
API GBIF công khai, gọi thẳng là cách nên dùng. Proxy không mở được trần offset, không đổi giấy phép. Cách đặt nhịp gọi khi đi qua proxy có ở bài rate limit API khi dùng proxy. Cách ghi chuỗi proxy có ở bài định dạng proxy, vai trò proxy trong thu thập có ở bài Web Scraping proxy là gì. Khi cần IP Việt Nam cho tác vụ khác, anh em có thể mua proxy tại trang chủ ProxyVN.
Ghi tham số truy vấn
Mỗi tệp dữ liệu đi kèm URL truy vấn, count, ngày gọi và các ngưỡng lọc. Với dữ liệu công bố, ghi thêm DOI của lần tải xuống. Không có tham số thì không ai tái lập được bản đồ.
Khóa phiên bản
Lab gọi API v1 với Python 3.12.10, requests 2.34.2. Đặc tả OpenAPI là nguồn tham số. Giữ bản đặc tả đã đọc cùng dự án.
Một điểm GBIF là một lần ghi nhận có độ bất định, có nguồn và có giấy phép. Không phải một cá thể, không phải tọa độ chính xác, không phải dữ liệu tự do mặc định.
GBIF occurrence API: câu hỏi thường gặp
Các câu dưới đây gom những điểm hay bị hỏi.
Có cần tài khoản không?
Không cho tìm kiếm. Cần cho API tải xuống có DOI.
Vì sao tìm theo key loài lại ra key khác?
Tìm theo taxonKey gồm cả đơn vị dưới loài. Giữ taxonKey của từng bản ghi.
Thiếu độ bất định thì coi là chính xác?
Không. Xếp vào nhóm không biết độ chính xác.
Lấy quá 100000 bản ghi thế nào?
Dùng API tải xuống. Tìm kiếm phân trang trả 400 khi vượt trần offset.
Có cộng được số đếm GBIF với iNaturalist?
Không vô điều kiện. GBIF đã chứa một phần bản ghi iNaturalist.
License trong facet và trong bản ghi khác nhau?
Cùng giấy phép, khác dạng ghi. Chuẩn hóa trước khi lọc.
Có nên dùng hasGeospatialIssue false mặc định?
Hợp lý cho bản đồ, nhưng ghi rõ trong phương pháp. Một số issue địa lý không nghiêm trọng vẫn bị loại theo cờ này.
Bản ghi PRESERVED_SPECIMEN có cần xử lý khác?
Có. Mẫu vật có số hiệu bảo tàng, thường cũ hơn và có thể có tọa độ suy từ địa danh. Kiểm eventDate và độ bất định riêng cho nhóm này.
Có nên tin tọa độ của mẫu vật cũ?
Cẩn thận. Mẫu vật thu từ nhiều thập kỷ trước thường có tọa độ được số hóa từ mô tả địa danh. Xem độ bất định và ghi chú địa điểm trước khi đặt lên bản đồ chi tiết.
Một bản ghi có thể bị gỡ khỏi GBIF không?
Có. Khi bộ dữ liệu gốc được cập nhật, bản ghi có thể biến mất hoặc đổi nội dung. Ghi ngày gọi và giữ bản sao dữ liệu đã dùng.
GBIF occurrence API và những điều cần nhớ
GBIF occurrence API cho bảng phân bố đáng tin khi đọc coordinateUncertaintyInMeters và basisOfRecord cho từng bản ghi, lọc từng bước có ghi số còn lại, chuẩn hóa giấy phép và giữ datasetKey để trích dẫn. Đừng coi bản ghi là cá thể, đừng suy tỉ lệ từ trang đầu, và đừng cộng với nguồn gốc mà GBIF đã gom. Proxy.vn - Nhà cung cấp dịch vụ proxy chất lượng hàng đầu Việt Nam khuyên anh em giữ bảng lọc chất lượng đi cùng mọi bản đồ dựng từ GBIF occurrence API.
