Contents

OnoGraph API Use Guidance

This page provides important technical details for using the API.

  • All names sent to the API should be encoded in UTF-8. Names containing diacritics/accents, e.g. Müller are unlikely to return results or return the wrong results if they are not encoded in UTF-8.
  • The API is case insensitive.
  • The API currently only works with the Latin alphabet and can accept any Latin alphabetic character.
  • Beyond Latin characters the only other characters that can be used are space ( ), hyphen (-) and apostrophe (').
  • Forenames supplied with a middle name, e.g. Maria del Carmen will not return any results. Only forenames with a suffix and a space may provide results, e.g. La Tonya, Abd Rahman or St John.
  • Dual surnames provided as a surname may provide results, but should be split with the second part provided as a second surname for better results.
  • The API is sensitive to diacritic marks or accents. For example Jovanovic and Jovanović, Yilmaz and Yılmaz, Muller and Müller, Szucs and Szűcs return different results. Such names with accents are typically borne by people living in their homelands. Such diacritic marks are almost always dropped upon emigration.
  • It is advised to remove any names with single character elements, e.g. with the forename 'A'. Making API calls for single-character names will considerably reduce accuracy. To our knowledge the only single character name elements are: A, E, I, O, U and Y. All of which are East Asian names.
  • Chinese forenames appear without a hyphen, e.g. Qingxiong.
  • Chinese names with adopted Western forenames, e.g. Andy Chan, will provide less accurate results.
  • The names of people living in Ukraine have been transliterated using the Ukrainian government's latest rules, though it is usually more common to use Russian transliteration.
  • All diacritics/accents have been removed from Vietnamese names.
  • Korean forenames appear with a hyphen, e.g. Gwang-jae.
  • Armenian names in Armenia, the former Soviet Union, Lebanon, Georgia and Iran almost always appear with the -yan suffix; while elsewhere they tend to appear with -ian.
  • Azeri names do not occur with the 'ə' character. They have been transliterated as 'a', 'e' or 'eh'.