Logo NameAPI

NameAPI REST API

HTTP://api.nameapi.org/rest/v5.3

The REST API as Swagger specification for the nameapi.org web services.

Version v5.3

Terms of Service

Apache 2.0

APIs

/development/exceptionthrower

GET

Tell the server to throw an exception.

This is useful for developing against server exceptions. What happens on invalid input, and so on. Just tell the server to throw one, and see what happens in your code and how you handle it.

Request

Parameters
Name Located in Required Description Default Schema
apiKey query yes The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query yes Set this to true to get a JSON envelope. - boolean
exceptionType query yes Which exception you'd like to receive. - string
exceptionChance query yes Should the server always throw, or just sometimes? 0-100 where 100 means 100% chance of throwing. - integer (int32)

Response

Content-Type: application/json

Status Code Reason Response Model
200 Returns 'OK' in case the server doesn't throw.
400 Bad Request -
401 Unauthorized -
403 Forbidden -
500 Internal Server Error -

/email/disposableemailaddressdetector

GET

Trash email detection.

Tells whether an email address is a disposable one.

Request

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
emailAddress query no The email address. Example: "DaDiDoo@mailinator.com" - string

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation DisposableEmailAddressDetectorResult

/email/emailnameparser

GET

Email name parser.

Parses the person's name out of an email address.

Request

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
emailAddress query no The email address. - string

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation EmailNameParserResult

POST

Email name parser.

Parses the person's name out of an email address.

Request

Content-Type: application/json

Parameters
Name Located in Required Description Default Schema
apiKey query yes The api-key also known as user-id. Authentication and accounting is performed on the server for this key. - string
envelope query yes Set this to true to get a JSON envelope. - boolean
body body yes Object containing the context and the email address. - InputWithEmail

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation EmailNameParserResult

/formatter/personnameformatter

POST

Person name formatter.

Formats a person's name in correct case and name order.

Request

Content-Type: application/json

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
body body no Object containing the context, the input person and the formatter properties. - PersonNameFormatterInput

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation FormatterResult

/genderizer/persongenderizer

POST

Person gender detector.

Attempts to detect a person's gender based on the name.

Request

Content-Type: application/json

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
body body no Object containing the context and the input person. - InputWithPerson

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation GenderizerResult

/matcher/personmatcher

POST

Compares people's names and attributes.

Compares two people to compute a similarity score. Are they the same, or just similar, or different?

Request

Content-Type: application/json

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
body body no Object containing the context and the 2 input persons. - InputWithTwoPeople

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation PersonMatcherResult

/parser/personnameparser

POST

Parses a person's raw name.

Identifies the individual name parts.

Request

Content-Type: application/json

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
body body no Object containing the context and the input person. - InputWithPerson

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation PersonNameParserResult

/riskdetector/person

POST

Checks whether data is fake or not.

Request

Content-Type: application/json

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean
body body no Object containing the context and the input person. - InputWithPerson

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation RiskDetectorResult

/system/ping

GET

Ping the server

Gives you a hint of the raw network time it takes for a round trip to the server and back, through the whole web service stack.

Request

Parameters
Name Located in Required Description Default Schema
apiKey query no The api-key also known as user-id. Authentication and accounting is performed on the server for this key. Example: "32d21gc5071d7463ef6064c07ea98cb2-user1" - string
envelope query no Set this to true to get a JSON envelope. - boolean

Response

Content-Type: application/json

Status Code Reason Response Model
200 Returns 'pong'

Definitions

AddressRelation

name type required description example
address InputAddress optional Returns the address for that relation.
usageForAll boolean optional If the address is used for all purposes then #getSpecificUsage returns null.
specificUsage array[string] optional

Returns 1-n usages for that address or absent if #isUsageForAll returns true.

See https://goo.gl/RXDiQF for the documentation of the AddressUsage enum values.

AgeInfo

name type required description example
empty boolean optional Tells if the object contains no data at all.
month integer (int32) optional 1-2-digit month from 1-12
year integer (int32) optional This may either be known as such, or be extracted out of a birth date. 4 digits, for example 1986.
day integer (int32) optional 1-2-digit day from 1-31
yearRange YearRange optional This may either be known as such, or be extracted out of another value such as a birth date.

AgeMatcherResult

name type required description example
matchType string optional Tells how two ages match. See https://goo.gl/J5h3sv for the documentation of the AgeMatchType enum values.

BirthDate

Implementation of AgeInfo.

name type required description example
month integer (int32) optional 1-2-digit month from 1-12
year integer (int32) optional 4 digits, for example 1986.
day integer (int32) optional 1-2-digit day from 1-31

BirthYear

Implementation of AgeInfo.

name type required description example
year integer (int32) optional This may either be known as such, or be extracted out of a birth date. 4 digits, for example 1986.

BirthYearMonth

Implementation of AgeInfo.

name type required description example
month integer (int32) optional 1-2-digit month from 1-12
year integer (int32) optional 4 digits, for example 1986.

BirthYearRange

Implementation of AgeInfo.

name type required description example
yearStartIncl integer (int32) optional 4-digit start year including
yearEndIncl integer (int32) optional 4-digit end year including

Context

name type required description example
priority string optional Tells whether someone (a human or a program) is waiting for the answer or not.
place string optional The geographic area from where the request is coming.

This helps the server to better understand and classify the incoming data. Example: the given name "Andrea" is female in Germany but male in Italy.

Value: A geographic code such as an ISO-3166 two letter country code, for example "FR" for France.

If the request is made in behalf of another company then the place may be adjusted to that. However, it is not meant to be set for the target customer. Example: Your company mainly operates in France (FR), and is the service provider for another company in Italy (IT), and the customer used in this web service request happens to be from Austria (AT), then the place should be set to "IT".

Technical note: when the system needs a Locale it uses the place with the language.

language string optional The language used for locale-sensitive operations such as converting a string to upper case. This is usually the primary language matching the {@link #place}, for example German for Germany.

If not provided, and {@link #place} is available, the primary language for that place is used.

Value: A language code such as an ISO-639-1 two letter code, for example "fr" for French.

Technical note: when the system needs a Locale it uses the place with the language.

writingSystems array[string] optional The writing system(s) used in the data source.

One code starts with the ISO 15924 script name, optionally followed by the ISO 639-1 or ISO 639-3 language code.

Examples: "Latn:de", "Latn:gsw", "Cyrl:ru".

Multiple writing systems may be used, for example "Cyrl:sr" plus "Latn:sr".

The special non-standard script name "Asci" is used for the us-ascii character set.

This hint helps the server to match terms with its databases, and generate better results. Also, the user may be warned when accidentally using characters not in his range, for example when a Cyrillic character slipped into his Latin customer database (which may be visually indistinguishable).

textCase string optional Tells in what case of writing (upper, lower ...) the data is sent to the server. See https://goo.gl/5gWeJX for the documentation of the TextCase enum values.
properties array[ContextProperty] optional

Arguments to send to the server. There are a few public properties. And custom properties may be created for customers to customize server behavior for their needs.

ContextProperty

name type required description example
name string optional The name of the property.
value string optional The value of the property.

DetectedRisk

name type required description example
dataItem string optional Tells which part of the user's input raised the risk alert. See https://goo.gl/kS67Ao for the documentation of the DataItem enum values.
riskType RiskType optional

Tells what kind of risk was detected.

Risk types:

  • FakeRiskType - classification of fake risks. In some situations the exact classification is difficult. For example a person's name may be from fiction, but also be famous at the same time. See https://goo.gl/2dFKhy
  • DisguiseRiskType - classification of disguise risks. Such mangled input is used to circumvent machine processing. Humans can still understand these modified values, but machines can't unless they detect the patterns and clean the input. See https://goo.gl/zw1kt1

riskScore number (double) optional The risk score of this data item, range (0,1], the higher the worse.
reason string optional A one sentence text reason that explains the risk for the human.

DisposableEmailAddressDetectorResult

name type required description example
disposable string optional The result of the disposable email address detector. See https://goo.gl/EHZ4VT for the documentation of the Maybe enum values.

EmailAddress

name type required description example
emailAddress string optional The email address, for example "john@example.com".

EmailAddressImpl

Implementation of EmailAddress.

EmailNameParserMatch

name type required description example
givenNames array[NameFromEmailAddress] optional The extracted given names from the email address.
surnames array[NameFromEmailAddress] optional The extracted surnames from the email address.
confidence number (double) optional A value in the range 0-1 that indicates how sure the server is about the result. The higher the better.

EmailNameParserResult

name type required description example
resultType string optional Tells what was detected in the local-part (user name) of the email address.
nameMatches array[EmailNameParserMatch] optional A list of successful ways of parsing a name out of an email address.

Enum

name type required description example

FieldType

name type required description example
enum Enum optional

The values are organized by culture. The name types that are often used in the USA are in the AmericanNameFieldType}, and so on. Certain values appear in multiple but their meaning is the same.

Name field types:

  • AmericanNameFieldType - Contains the name field types that are often used in America. See https://goo.gl/WP85x8
  • ArabicNameFieldType - The traditional name fields of the Arabic culture. See https://goo.gl/cgH7gw
  • CommonNameFieldType - Contains the name field types that are commonly shared by many cultures. See https://goo.gl/eKR6Em
  • LegalNameFieldType - Contains the field types that are used by organizations. See https://goo.gl/uY2zwQ
  • OtherNameFieldType - A place for "other" types that don't fit into Common and are not too culture specific. See https://goo.gl/Gt7cZg
  • WesternNameFieldType - Currently no values here, they all fit into CommonNameFieldType.

FormatterProperties

name type required description example
dummy boolean optional The properties will be defined in a future version. There are many options how it could be implemented, no decision has been made yet.

FormatterResult

name type required description example
formatted string optional The nicely formatted string, possibly the same as the input.
unknown boolean optional If true then server didn't understand the input, but still tried to format it. This feature must be enabled specifically in the input properties.

GenderMatcherResult

name type required description example
matchType string optional Tells how the 2 genders matched. See https://goo.gl/iJQSBf for the documentation of the GenderMatchType enum values.
confidence number (double) optional A value in the range 0-1 that indicates how sure the server is about the result. The higher the better.
warnings array[string] optional Messages describing possible problems that were identified.

GenderizerResult

name type required description example
gender string optional The computed gender result. See https://goo.gl/LkJBZG for the documentation of the ComputedPersonGender enum values.
maleProportion number (double) optional If the computed gender is neutral this may be specified (but does not have to be). A value 0-1, the remaining percentage is for the female gender.
confidence number (double) optional A value in the range 0-1 that indicates how sure the server is about the result. The higher the better.

InputAddress

name type required description example
streetInfo StreetInfo optional Information about the street name, street number, apartment/suite. Missing if no street/house information is known at all, for example because it's a postbox address, or if it's a raw address.
addressLines array[string] optional Returns the address information line by line.
placeInfo PlaceInfo optional Information about the locality. Missing if it's a raw address.
pobox string optional Usually the post box number as it appears in the address. If the string is non-null then it's not empty, and contains either a number, or a string like "postbox", or both like "Po box 2435" etc.

InputPerson

name type required description example
correspondenceLanguage string optional The language code for the correspondence language of the person (with you, the company).

ISO-639 code of the language. Either 639-1 or 639-3, for example "it" or "ita" for Italian.

Usage: In combination with the Context.place it helps the services to better classify the culture of the person.

Invalid input: The behavior on illegal input depends on the web service that is called. It may ignore it, or throw an invalid input exception.

emailAddresses array[EmailAddress] optional Email addresses that are used by this person.

Multiple addresses may be added.

Usage: Depends on the service. A data validator service may check for problems such as illegal syntax or inexistent domain. A service may check for disposable email addresses. It may be used to extract name information. A validator service may compare the name in the email address with the person's name.

Invalid input: The behavior on illegal input depends on the web service that is called. A validator service may report problems with invalid email address syntax, or inexistent domain names, etc. Services may throw an invalid input exception.

telNumbers array[TelNumber] optional Phone, fax etc numbers that are used by this person.

Multiple numbers may be added.

Usage: Depends on the service. A data validator service may check for problems. A fake checker may look for suspicious input.

Invalid input: The behavior on illegal input depends on the web service that is called. A validator service may report problems with an address. Other services mostly just ignore invalid phone data as it is not their task to validate, and the information is just helping to better understand the input and is not essential.

addresses array[AddressRelation] optional Addresses that are used by this person.

Multiple addresses may be passed (domicile, mailing/delivery address, ...) or a single address may be responsible for all purposes.

Usage: Depends on the service. A validator service may check for valid addresses, and report problems (such as invalid zip codes). A genderizer service may use it to better classify the names.

Invalid input: The behavior on illegal input depends on the web service that is called. A validator service may report problems with an address. Other services mostly just ignore invalid address data as it is not their task to validate, and the information is just helping to better understand the input and is not essential.

personName InputPersonName optional Defines a person's names such as given name(s) and surname(s). Multiple given names may appear in one field. Or they can be added as multiple name items if they are available separately already. The same applies for other name types such as surnames.
age AgeInfo optional Information about a person's age. For a NaturalPerson this is the birth-date/age info. For a LegalPerson this is the founding date (activation date).

Usage: Depends on the service. A validator service may check for valid dates, and report problems (such as 1986-02-31). A genderizer service may use it to filter irrelevant birth statistics.

Invalid input: The behavior on illegal input depends on the web service that is called. Invalid (xml) input such as a non-numeric string should always result in an illegal input exception. An invalid date such as 1986-02-31 may trigger an illegal input exception, or it may just be ignored.

InputPersonName

name type required description example
nameFields array[NameField] optional A list of input fields for a name or name-related input, such as a given name.

InputWithEmail

name type required description example
context Context optional The context defining the caller's environment for the execution.
emailAddress string required The email address, for example "test@example.com".

InputWithPerson

name type required description example
context Context optional The context defining the caller's environment for the execution.
inputPerson InputPerson required A natural or legal person as used in crm databases, online user databases etc.

InputWithTwoPeople

name type required description example
context Context optional The context defining the caller's environment for the execution.
inputPerson1 InputPerson optional The first natural or legal person as used in crm databases, online user databases etc.
inputPerson2 InputPerson optional The second natural or legal person as used in crm databases, online user databases etc.

LegalInputPersonImpl

Implementation of InputPerson used for legal entities.

name type required description example
emailAddresses array[EmailAddress] optional Email addresses that are used by this person. See InputPerson.
correspondenceLanguage string optional The language code for the correspondence language of the person (with you, the company). See InputPerson.
personName InputPersonName optional Defines a person's names such as given name(s) and surname(s). See InputPerson.
age AgeInfo optional Information about a person's age. See InputPerson.
telNumbers array[TelNumber] optional Phone, fax etc numbers that are used by this person. See InputPerson.
addresses array[AddressRelation] optional Addresses that are used by this person. See InputPerson.

MultiLineAddress

Implementation of InputAddress where the address lines only exist in the form of text lines. Specific data such as street name and postal code are not known, they need to be parsed/extracted.

name type required description example
addressLines array[string] optional The address information that appears in the form of text lines.

NameField

name type required description example
string string optional The string on the input.
fieldType FieldType optional

The field type, a common interface for the enum values.

NameFromEmailAddress

name type required description example
name string optional The name extracted from the email address.
nameType string optional What kind of name string it is. See https://goo.gl/2UYPsJ for the documentation of the EmailAddressNameType enum values.

NaturalInputPersonImpl

Implementation of InputPerson used for natural people.

name type required description example
emailAddresses array[EmailAddress] optional Email addresses that are used by this person. See InputPerson.
correspondenceLanguage string optional The language code for the correspondence language of the person (with you, the company). See InputPerson.
personName InputPersonName optional Defines a person's names such as given name(s) and surname(s). See InputPerson.
age AgeInfo optional Information about a person's age. See InputPerson.
telNumbers array[TelNumber] optional Phone, fax etc numbers that are used by this person. See InputPerson.
addresses array[AddressRelation] optional Addresses that are used by this person. See InputPerson.
gender string optional

The gender of the person. This is how common database applications usually store the gender for a person.

See https://goo.gl/VDz19f for the documentation of the StoragePersonGender enum values.
maritalStatus string optional

Defines the person's marital status.

See https://goo.gl/BL4Ue8 for the documentation of the MaritalStatus enum values.
nationalities array[string] optional

The nationalities eg [DE,FR] in upper case, or null if the info is not available. The method should not return an empty collection in case the nationality of a person is unknown. There are few people without nationality, but they exist, and that would be the correct case for an empty collection.

nativeLanguages array[string] optional

The mother tongue(s), or null if the information is not available. The method should not return an empty collection in case the mother tongue of a person is unknown. There are not too many people without any mother tongue, but it exists, and then that would be the correct case for an empty collection.

religion string optional A NameProfiler religion code such as "AB.CR" for Christianity.

NullAgeInfo

Implementation of AgeInfo that doesn't contain any information.

name type required description example
month integer (int32) optional Absent.
year integer (int32) optional Absent.
day integer (int32) optional Absent.
yearRange YearRange optional Absent.

OutputPersonName

name type required description example
terms array[Term] optional The list of extracted name related terms from the input person.

ParsedPerson

name type required description example
personType string optional The type of person, it can be types of natural and legal people, and groups of them. See https://goo.gl/1iwt9p for the documentation of the PersonType enum values.
personRole string optional The role of the person. For example it can be the receiver, the owner or just a contact. See https://goo.gl/xVhJXh for the documentation of the PersonRole enum values.
mailingPersonRoles array[string] optional The roles of a person within a mailing address. It is of interest once not only a single, but multiple entities are mentioned. See https://goo.gl/11XqE5 for the documentation of the MailingPersonRole enum values.
gender GenderizerResult optional The result of the Genderizer containing the gender, optionally the male proportion and the confidence.
addressingGivenName string optional The given name that may be used when addressing the person.
addressingSurname string optional The surname that may be used when addressing the person.
outputPersonName OutputPersonName optional All the names identified in an input person name.
people array[ParsedPerson] optional The list of people parsed from the input.

ParsedPersonMatch

name type required description example
parsedPerson ParsedPerson optional Information about the person: the computed gender, the addressing given name, the addressing surname...
parserDisputes array[ParserDispute] optional A list of consistency problems detected by the parser is within this object.
likeliness number (double) optional A value in the range 0-1 that indicates how likely is it that this is the correct way of parsing. The higher the better.
confidence number (double) optional A value in the range 0-1 that indicates how sure the server is about the result. The higher the better.

ParserDispute

name type required description example
disputeType string optional The type of consistency problem detected by the name parser. See https://goo.gl/Y4yNhc for the documentation of the DisputeType enum values.
message string optional The explanation of the detected dispute.

PersonMatcherResult

name type required description example
matchType string required The overall result of the matching. See https://goo.gl/aW7FVo for the documentation of the PersonMatchType enum values.
personMatchComposition string required Tells how much the two people have in common. See https://goo.gl/SRpAgM for the documentation of the PersonMatchComposition enum values.
points number (double) required A value in the range -1 to 1 that indicates how well the two people match (positive points) or how much they mismatch (negative points).
confidence number (double) required A value in the range 0-1 that indicates how sure the server is about the result. The higher the better.
personNameMatcherResult PersonNameMatcherResult required The result of comparing the names of the 2 people. It contains all possible ways of comparing the name pairs, and offers the best.
genderMatcherResult GenderMatcherResult required The result of comparing the genders of the 2 people.
ageMatcherResult AgeMatcherResult required The result of comparing the ages of the 2 people.

PersonNameFormatterInput

name type required description example
context Context optional The context defining the caller's environment for the execution.
inputPerson InputPerson optional A natural or legal person as used in crm databases, online user databases etc.
properties FormatterProperties optional The properties will be defined in a future version. There are many options how it could be implemented, no decision has been made yet.

PersonNameMatcherResult

name type required description example
matchType string optional The overall match type of how the names of one person match vs the names of another person. See https://goo.gl/iDDBom for the documentation of the PersonNameMatchType enum values.

PersonNameParserResult

name type required description example
matches array[ParsedPersonMatch] optional A list of possible ways how a person could be parsed. The entries are sorted by likeliness & confidence, the first is the best parsing result.

PlaceInfo

name type required description example
country string optional

The country code or name in any language.

Examples:
  • "DE" Germany (ISO 3166-alpha2 code)
  • "Germany"
  • "U.S.A."
region string optional

The region or region code (state, county, province), such as "CA" in the USA for California.

Examples:
  • "CA" for California USA
  • "Jud. Brasov" in Romania
localityAndPostalCode string optional

Returns the locality and postal code, in any order.

Whether the postal code or the locality comes first depends on stuff. How it's entered, how it's common for the country, etc.

When the data is available separate in #getLocality and #getPostalCode then this method here returns a combination of those. The implementation is advised to concatenate the values in a format which is suitable for the customs. For example a specialized GermanAddress would append the locality after the postal code, separated by a space.

asString string optional The whole place information in a single string.
locality string optional The city/town/village/municipality/place name.
neighborhood string optional

The city area/neighborhood/district/sector information.

Examples:
  • "Vila Industrial" in Brazil
  • "Sector 6" in Romania, only used in the capital Bucharest
asLines array[string] optional Returns the whole place information as text lines, containing at least 1 line. If there are two lines then it is common that the first line contains the #getPostalCode and the #getLocality and other things especially the #getCountry() come on another line.
postalCode string optional

The postal code should not be prefixed with a country code that is not part of the postal code itself, such as an ISO 3166-1 alpha-2 code. Example: "FR-71320" or "F-71320". If possible then the country code should be dropped. The ISO 31-66-1 alpha-2 maybe directly used as the {@link #getCountry country} instead.

Examples:
  • "94107" USA
  • "H3Z 2Y7" Canada
  • "8022" Switzerland
  • "CH-8022" Switzerland, european style of adding country code as prefix

RiskDetectorResult

name type required description example
score number (double) optional

An overall score considering all the detected risks and all the positive attributes of the record.

Range [-1,1] where:

  • [-1,0) means no risks were detected and the record looks good.
  • 0 means no risks were detected, but also no positive attributes were found, the service can't tell for sure.
  • (0,1] means one or multiple risks were detected.
risks array[DetectedRisk] optional A list of detected risks in the InputPerson data. The list can be empty.

RiskType

name type required description example

SimpleTelNumber

Implementation of TelNumber that does not specify any more detail such as separated country code or area prefix.

name type required description example
fullNumber string optional The complete number in any format. Not empty.

SingleStringAddress

Implementation of InputAddress where the address is in one single line.

name type required description example
string string optional The address information that appears in one single line. May not be empty and line breaks are not allowed!

SingleStringStreetInfo

Implementation of StreetInfo where the information is in one single line.

name type required description example
string string optional

Impl where the whole street/house etc information is in plaintext form in a single line and needs to be parsed to extract information.

It contains at least a street name, but may contain all other kinds of information also such as apartment/suite etc.

SpecificUsageAddressRelation

Implementation of AddressRelation that specifies for what purposes a certain InputAddress is, for example for CORRESPONDENCE.

name type required description example
address InputAddress optional Represents a physical address which can be an address to a house, a postbox, a "packet pickup station" etc.
usage InputAddress optional Represents a physical address which can be an address to a house, a postbox, a "packet pickup station" etc.

StreetInfo

name type required description example
streetNameAndNumber string optional Returns the street name possibly with a number.
streetName string optional The street name alone, or absent if this info is not available or not available alone.
apartment string optional The apartment/suite, or absent if this info is not available or not available alone.
asString string optional The whole street information in a single string.
floor string optional The floor number, or absent if this info is not available or not available alone.
staircase string optional The staircase identifier, or absent if this info is not available or not available alone.
houseNumber string optional Something like "15" or "15-17" or "15b" etc. The house number/identifier alone, or absent if this info is not available or not available alone.
addressLine2 string optional Returns the information from the fields for building, staircase, floor and apartment.
asLines array[string] optional Returns the whole street information as text lines, containing at least 1 line.
building string optional The building identifier, or absent if this info is not available or not available alone.

StructuredAddress

Implementation of InputAddress where the individual parts (street name, postal code, ...) are structured into separate values.

name type required description example
streetInfo StreetInfo optional Information about the street name, street number, apartment/suite. Missing if no street/house information is known at all, For example because it's a postbox address, or if it's a raw address.
pobox string optional The postal box information.
placeInfo PlaceInfo optional Information about the locality, possibly including: locality, postal code, neighborhood, region (state), country.

StructuredPlaceInfo

Implementation of PlaceInfo where the individual parts (postalCode, region, country) are structured into separate values.

name type required description example
locality string optional The locality. See PlaceInfo.
postalCode string optional The postal code. See PlaceInfo.
neighborhood string optional The neighborhood. See PlaceInfo.
region string optional The region. See PlaceInfo.
country string optional The country. See PlaceInfo.

StructuredStreetInfo

Implementation of StreetInfo where the individual parts (streetName, houseNumber, apartment...) are structured into separate values.

name type required description example
streetName string optional The streetName. See StreetInfo.
houseNumber string optional The house number. See StreetInfo.
building string optional The building. See StreetInfo.
staircase string optional The staircase. See StreetInfo.
floor string optional The floor. See StreetInfo.
apartment string optional The apartment. See StreetInfo.

TelNumber

name type required description example
fullNumber string optional

Returns the complete number in any format. This is the minimal required api for all implementations.

Implementations may provide additional getters for information such as:

  • type of number (phone, fax, mobile, fixed, ...)
  • separate country code, area code and number

Term

name type required description example
string string optional The string of the term.
termType string optional The type of the term. See https://goo.gl/FtesDX for the documentation of the TermType enum values.

UseForAllAddressRelation

Implementation of AddressRelation that specifies that the address is used for all purposes.

name type required description example
address InputAddress optional Represents a physical address which can be an address to a house, a postbox, a "packet pickup station" etc.
specificUsage array[string] optional Lists the possible purposes of an input address. See https://goo.gl/uap11n for the documentation of the AddressUsage enum values.

YearRange

name type required description example
startIncluding integer (int32) optional The start year, for example 1980. Absent if not known.
endIncluding integer (int32) optional The end year, for example 1989. Absent if not known.