Package: pyopenfigi
pyopenfigiPython wrapper for theOpenFIGI APIv3.Table of contentsAbout OpenFIGIInstallationAPI keyMappingFilteringTroubleshootingAbout OpenFIGITheFinancialInstrumentGlobalIdentifier (FIGI) is a universal system for identifying instruments
globally and across all asset classesOpenFIGI is an application programming interface that provides automated access
to mapping various symbols with their corresponding FIGI. It is available athttps://www.openfigi.com/pyopenfigiis a
thin Python wrapper to access OpenFIGIThe API contains 3 endpoints:endpointdescription/mappingMap third-party identifiers to FIGIs/filterFilter for FIGIs using keywords and optional filters/searchSearch for FIGIs using keywords and optional filtersNote: given that the/searchendpoint is strictly superseded by the/filterendpoint, we
choose not to include it in the wrapper.Installationpyopenfigiis published onPyPI. To install it, simply run:pip install pyopenfigiAPI keyThe API can be used with or without API key.
Getting an API key is free and loosens therate limits.When instantiating the wrapper, the API key is optional:frompyopenfigiimportOpenFigiwrapper=OpenFigi()wrapper=OpenFigi(api_key="XXXXXXXXXX")MappingThemap()method takes a list ofMappingJobas argument and returns a list ofMappingJobResult. The
result of the request at indexiin the list of mapping jobs is located at indexiin the list of results.frompyopenfigiimportOpenFigi,MappingJobmapping_job=MappingJob(id_type="TICKER",id_value="IBM",exch_code="US")mapping_jobs=[mapping_job]results=OpenFigi().map(mapping_jobs)>>>results[MappingJobResultFigiList(data=[FigiResult(figi='BBG000BLNNH6',security_type='Common Stock',market_sector='Equity',ticker='IBM',name='INTL BUSINESS MACHINES CORP',exch_code='US',share_class_figi='BBG001S5S399',composite_figi='BBG000BLNNH6',security_type2='Common Stock',security_description='IBM',metadata=None)])]AMappingJobResultcan either be aMappingJobResultFigiList, aMappingJobResultFigiNotFoundor aMappingJobResultError.TheMappingJobobject has 2 required properties which areid_typeandid_value. The other properties are optional
but subject to specific rules in case they are provided. These rules are modeled and checked usingPydantic.Below is the full list of properties forMappingJob:propertyrequiredtypeexampleid_typeXstr"TICKER"id_valueXstr"IBM"exch_codestr"UN"mic_codestr"XNYS"currencystr"USD"market_sec_desstr"Equity"security_typestr"Common Stock"security_type_2str"Common Stock"include_unlisted_equitiesbooloption_typestr"Call"strikelist[100, 200]contract_sizelist[0, 100]couponlist[0, 2.5]expirationlist[date(2023, 6, 1), date(2023, 12, 31)]maturitylist[date(2023, 6, 1), date(2023, 12, 31)]state_codestr"AZ"Some of the properties in theMappingJobare "enum-like". For each of these properties, it is possible to
retrieve the current list of accepted values via specific methods:propertymethodexamplesid_typeget_id_types()exch_codeget_exch_codes()mic_codeget_mic_codes()currencyget_currencies()market_sec_desget_market_sec_des()security_typeget_security_types()security_type_2get_security_types_2()state_codeget_state_codes()For example, to retrieve the current values forid_type:frompyopenfigiimportOpenFigiid_types=OpenFigi().get_id_types()FilteringThefilter()method takes aQueryobject as argument and returns a list ofFigiResult.TheQueryobject is very similar to theMappingJobobjectThe only difference are that theid_typeandid_valueare replaced by a singlequerypropertyAll the "enum-like" properties are the same and the list of accepted values is the sameThe maximum number of results is limited to 15,000propertyrequiredtypeexamplequeryXstr"SJIM"exch_codestr"UN"mic_codestr"XNYS"currencystr"USD"market_sec_desstr"Equity"security_typestr"Common Stock"security_type_2str"Common Stock"include_unlisted_equitiesbooloption_typestr"Call"strikelist[100, 200]contract_sizelist[0, 100]couponlist[0, 2.5]expirationlist[date(2023, 6, 1), date(2023, 12, 31)]maturitylist[date(2023, 6, 1), date(2023, 12, 31)]state_codestr"AZ"ExamplefrompyopenfigiimportOpenFigi,Queryquery=Query(query="SJIM")results=OpenFigi().filter(query)In order to know the total number of matches for a given query before starting to request them, it is possible to use
theget_total_number_of_matches()method:frompyopenfigiimportOpenFigi,Queryquery=Query(query="SJIM")number_of_results=OpenFigi().get_total_number_of_matches(query)>>>number_of_results36TroubleshootingSeveral kinds of errors can occur.ValidationError: theMappingJobandQueryobjects are modeled usingPydanticand therefore need to be
properly instantiated. If an error occurs, apydantic.exceptions.ValidationErrorwill be raised.HTTPError: in case the status code of the HTTP response is not 200, an HTTPError exception will be raised. Note:
in case a particular symbol is not found, the API will still respond with a status 200 and aMappingNotFoundobject. HTTP errors only occur if there is a real error like a malformedMappingJobrequest (which should not
happen since allMappingJobobjects are checked byPydanticprior to being sent), a rate limitation or an
internal server error.Here is how to check forValidationErrorin case the mapping jobs are instantiated programmatically:frompydanticimportValidationErrorfrompyopenfigiimportMappingJobtickers=["IBM","XRX","TSLA",None,"MSFT"]mapping_jobs=[]fortickerintickers:try:mapping_job=MappingJob(id_type="TICKER",id_value=ticker,exch_code="US")mapping_jobs.append(mapping_job)exceptValidationError:print(f"Error when trying to build a MappingJob with{ticker=}")# Do somethingcontinueAnd here is how to check forHTTPErrorin case exceptions need to be handled:frompyopenfigiimportOpenFigi,MappingJobfrompyopenfigi.exceptionsimportHTTPErrormapping_jobs=[MappingJob(id_type="TICKER",id_value="IBM",exch_code="US")]try:results=OpenFigi().map(mapping_jobs)exceptHTTPErrorase:print(f"{e}")# Do something